From 206cf74f0db5b885f447f9827d70f172c7471009 Mon Sep 17 00:00:00 2001
From: Piotr <piotrekkr@users.noreply.github.com>
Date: Wed, 7 Aug 2024 19:26:33 +0200
Subject: [PATCH] Update misleading note in
 section-defining-outputs-for-jobs.md (#33842)

Co-authored-by: Jacob Wallraff <thyeggman@github.com>
Co-authored-by: Alex Nguyen <150945400+nguyenalex836@users.noreply.github.com>
---
 .../jobs/section-defining-outputs-for-jobs.md | 48 ++++++++++++++++---
 1 file changed, 42 insertions(+), 6 deletions(-)

diff --git a/data/reusables/actions/jobs/section-defining-outputs-for-jobs.md b/data/reusables/actions/jobs/section-defining-outputs-for-jobs.md
index 43fd5265bab4..f37718764cf6 100644
--- a/data/reusables/actions/jobs/section-defining-outputs-for-jobs.md
+++ b/data/reusables/actions/jobs/section-defining-outputs-for-jobs.md
@@ -6,12 +6,6 @@ Job outputs containing expressions are evaluated on the runner at the end of eac
 
 To use job outputs in a dependent job, you can use the `needs` context. For more information, see "[AUTOTITLE](/actions/learn-github-actions/contexts#needs-context)."
 
-{% note %}
-
-**Note:** `$GITHUB_OUTPUT` is shared between all steps in a job. If you use the same output name in multiple steps, the last step to write to the output will override the value. If your job uses a matrix and writes to `$GITHUB_OUTPUT`, the content will be overwritten for each matrix combination. You can use the `matrix` context to create unique output names for each job configuration. For more information, see "[AUTOTITLE](/actions/learn-github-actions/contexts#matrix-context)."
-
-{% endnote %}
-
 ### Example: Defining outputs for a job
 
 {% raw %}
@@ -40,3 +34,45 @@ jobs:
 ```
 
 {% endraw %}
+
+### Using Job Outputs in a Matrix Job
+
+Matrices can be used to generate multiple outputs of different names. When using a matrix, job outputs will be combined from all jobs inside the matrix.
+
+{% raw %}
+
+```yaml
+jobs:
+  job1:
+    runs-on: ubuntu-latest
+    outputs:
+      output_1: ${{ steps.gen_output.outputs.output_1 }}
+      output_2: ${{ steps.gen_output.outputs.output_2 }}
+      output_3: ${{ steps.gen_output.outputs.output_3 }}
+    strategy:
+      matrix:
+        version: [1, 2, 3]
+    steps:
+      - name: Generate output
+        id: gen_output
+        run: |
+          version="${{ matrix.version }}"
+          echo "output_${version}=${version}" >> "$GITHUB_OUTPUT"
+  job2:
+    runs-on: ubuntu-latest
+    needs: [job1]
+    steps:
+      # Will show
+      # {
+      #   "output_1": "1",
+      #   "output_2": "2",
+      #   "output_3": "3"
+      # }
+      - run: echo '${{ toJSON(needs.job1.outputs) }}'
+```
+
+{% endraw %}
+
+{% warning %}
+Actions does not guarantee the order that matrix jobs will run in. Ensure that the output name is unique, otherwise the last matrix job that runs will override the output value.
+{% endwarning %}