From ea1c28d66c34b8400391ed74d510f66abc392d5e Mon Sep 17 00:00:00 2001
From: "Cloud Posse Bot (CI/CD)" <bot@cloudposse.com>
Date: Thu, 8 Dec 2022 05:54:09 -0800
Subject: [PATCH] Update README.md and docs (#13)

Co-authored-by: goruha <goruha@users.noreply.github.com>
---
 README.md | 288 ++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 249 insertions(+), 39 deletions(-)

diff --git a/README.md b/README.md
index 94662d6..81d9cfc 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 
 <!-- markdownlint-disable -->
-# example-github-action-composite [![Latest Release](https://img.shields.io/github/release/cloudposse/example-github-action-composite.svg)](https://github.com/cloudposse/example-github-action-composite/releases/latest) [![Slack Community](https://slack.cloudposse.com/badge.svg)](https://slack.cloudposse.com)
+# github-action-matrix-outputs-read [![Latest Release](https://img.shields.io/github/release/cloudposse/github-action-matrix-outputs-read.svg)](https://github.com/cloudposse/github-action-matrix-outputs-read/releases/latest) [![Slack Community](https://slack.cloudposse.com/badge.svg)](https://slack.cloudposse.com)
 <!-- markdownlint-restore -->
 
 [![README Header][readme_header_img]][readme_header_link]
@@ -28,7 +28,8 @@
 
 -->
 
-Template repository of composite GitHub Action
+[Workaround implementation](https://github.com/community/community/discussions/17245#discussioncomment-3814009) - Read matrix jobs outputs
+
 
 ---
 
@@ -58,8 +59,14 @@ It's 100% Open Source and licensed under the [APACHE2](LICENSE).
 
 ## Introduction
 
-This is template repository to create composite GitHub Actions. 
-Feel free to use it as reference and starting point.
+GitHub actions have an [Jobs need a way to reference all outputs of matrix jobs](https://github.com/community/community/discussions/17245) issue.
+If there is a job that runs multiple times with `strategy.matrix` only the latest iteration's output availiable for 
+reference in other jobs.
+
+There is a [workaround](https://github.com/community/community/discussions/17245#discussioncomment-3814009) to address the limitation.
+We implement the workaround with two GitHub Actions:
+* [Matrix Outputs Write](https://github.com/cloudposse/github-action-matrix-outputs-write)
+* [Matrix Outputs Read](https://github.com/cloudposse/github-action-matrix-outputs-read)
 
 
 
@@ -69,6 +76,8 @@ Feel free to use it as reference and starting point.
 
 
 
+Example how you can use workaround to reference matrix job outputs.
+
 ```yaml
   name: Pull Request
   on:
@@ -77,17 +86,217 @@ Feel free to use it as reference and starting point.
       types: [opened, synchronize, reopened, closed, labeled, unlabeled]
 
   jobs:
-    context:
+    build:
       runs-on: ubuntu-latest
+      strategy:
+        matrix:
+          platform: ["i386", "arm64v8"]
       steps:
-        - name: Example action
-          uses: cloudposse/example-github-action-composite@main
-          id: example
+        - name: Checkout
+          uses: actions/checkout@v3
+
+        - name: Build
+          id: build
+          uses: cloudposse/github-action-docker-build-push@1.9.0
           with:
-            param1: true
+            registry: registry.hub.docker.com
+            organization: "${{ github.event.repository.owner.login }}"
+            repository: "${{ github.event.repository.name }}"
+            build-args: |-
+              PLATFORM=${{ matrix.platform }}
+
+        ## Write for matrix outputs workaround 
+        - uses: cloudposse/github-action-matrix-outputs-write@0.3.1
+          id: out
+          with:
+            matrix-step-name: ${{ github.job }}
+            matrix-key: ${{ matrix.platform }}
+            outputs: |-
+              image: ${{ steps.build.outputs.image }}:${{ steps.build.outputs.tag }}
+
+    ## Read matrix outputs 
+    read:
+      runs-on: ubuntu-latest
+      needs: [build]
+      steps:
+        - uses: cloudposse/github-action-matrix-outputs-read@main
+          id: read
+          with:
+            matrix-step-name: build
 
       outputs:
-        result: ${{ steps.example.outputs.result1 }}
+        result: "${{ steps.read.outputs.result }}"
+
+    ## This how you can reference matrix output
+    assert:
+      runs-on: ubuntu-latest
+      needs: [read]
+      steps:
+        - uses: nick-fields/assert-action@v1
+          with:
+            expected: ${{ registry.hub.docker.com }}/${{ github.event.repository.owner.login }}/${{ github.event.repository.name }}:i386
+            ## This how you can reference matrix output
+            actual: ${{ fromJson(needs.read.outputs.result).image.i386 }}
+
+        - uses: nick-fields/assert-action@v1
+          with:
+            expected: ${{ registry.hub.docker.com }}/${{ github.event.repository.owner.login }}/${{ github.event.repository.name }}:arm64v8
+            ## This how you can reference matrix output
+            actual: ${{ fromJson(needs.read.outputs.result).image.arm64v8 }}
+```
+
+### Reusable workflow example 
+
+Reusable workflow that support matrix outputs
+
+`./.github/workflow/build-reusabled.yaml`
+
+```yaml
+name: Build - Reusable workflow
+on:
+  workflow_call:
+    inputs:
+      registry:
+        required: true
+        type: string
+      organization:
+        required: true
+        type: string
+      repository:
+        required: true
+        type: string
+      platform:
+        required: true
+        type: string
+      matrix-step-name:
+        required: false
+        type: string
+      matrix-key:
+        required: false
+        type: string
+    outputs:
+      image:
+        description: "Image"
+        value: ${{ jobs.write.outputs.image }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Build
+        id: build
+        uses: cloudposse/github-action-docker-build-push@1.9.0
+        with:
+          registry: ${{ inputs.registry }}
+          organization: ${{ inputs.organization }}
+          repository: ${{ inputs.repository }}
+          build-args: |-
+            PLATFORM=${{ inputs.platform }}
+    outputs:
+      image: ${{ needs.build.outputs.image }}:${{ needs.build.outputs.tag }}
+
+  write:
+    runs-on: ubuntu-latest
+    needs: [build]
+    steps:        
+      ## Write for matrix outputs workaround 
+      - uses: cloudposse/github-action-matrix-outputs-write@0.3.1
+        id: out
+        with:
+          matrix-step-name: ${{ inputs.matrix-step-name }}
+          matrix-key: ${{ inputs.matrix-key }}
+          outputs: |-
+            image: ${{ needs.build.outputs.image }}
+
+    outputs:
+      image: ${{ fromJson(steps.out.outputs.result).image }}
+```
+
+Then you can use the workflow with matrix
+
+```yaml
+name: Pull Request
+on:
+  pull_request:
+    branches: [ 'main' ]
+    types: [opened, synchronize, reopened, closed, labeled, unlabeled]
+
+jobs:
+  build:
+    usage: ./.github/workflow/build-reusabled.yaml
+    strategy:
+      matrix:
+        platform: ["i386", "arm64v8"]
+    with:
+      registry: registry.hub.docker.com
+      organization: "${{ github.event.repository.owner.login }}"
+      repository: "${{ github.event.repository.name }}"
+      platform: ${{ matrix.platform }}
+      matrix-step-name: ${{ github.job }}
+      matrix-key: ${{ matrix.platform }}
+
+  ## Read matrix outputs 
+  read:
+    runs-on: ubuntu-latest
+    needs: [build]
+    steps:
+      - uses: cloudposse/github-action-matrix-outputs-read@main
+        id: read
+        with:
+          matrix-step-name: build
+
+    outputs:
+      result: "${{ steps.read.outputs.result }}"
+
+  ## This how you can reference matrix output
+  assert:
+    runs-on: ubuntu-latest
+    needs: [read]
+    steps:
+      - uses: nick-fields/assert-action@v1
+        with:
+          expected: ${{ registry.hub.docker.com }}/${{ github.event.repository.owner.login }}/${{ github.event.repository.name }}:i386
+          ## This how you can reference matrix output
+          actual: ${{ fromJson(needs.read.outputs.result).image.i386 }}
+
+      - uses: nick-fields/assert-action@v1
+        with:
+          expected: ${{ registry.hub.docker.com }}/${{ github.event.repository.owner.login }}/${{ github.event.repository.name }}:arm64v8
+          ## This how you can reference matrix output
+          actual: ${{ fromJson(needs.read.outputs.result).image.arm64v8 }}
+```
+
+or as a simple job
+
+```yaml
+name: Pull Request
+on:
+  pull_request:
+    branches: [ 'main' ]
+    types: [opened, synchronize, reopened, closed, labeled, unlabeled]
+
+jobs:
+  build:
+    usage: ./.github/workflow/build-reusabled.yaml
+    with:
+      registry: registry.hub.docker.com
+      organization: "${{ github.event.repository.owner.login }}"
+      repository: "${{ github.event.repository.name }}"
+      platform: "i386"
+
+  ## This how you can reference single job output
+  assert:
+    runs-on: ubuntu-latest
+    needs: [build]
+    steps:
+      - uses: nick-fields/assert-action@v1
+        with:
+          expected: ${{ registry.hub.docker.com }}/${{ github.event.repository.owner.login }}/${{ github.event.repository.name }}:i386
+          ## This how you can reference matrix output
+          actual: ${{ needs.build.outputs.image }}
 ```
 
 
@@ -115,7 +324,7 @@ Feel free to use it as reference and starting point.
 
 ## Share the Love
 
-Like this project? Please give it a ★ on [our GitHub](https://github.com/cloudposse/example-github-action-composite)! (it helps us **a lot**)
+Like this project? Please give it a ★ on [our GitHub](https://github.com/cloudposse/github-action-matrix-outputs-read)! (it helps us **a lot**)
 
 Are you using this project or any of our other projects? Consider [leaving a testimonial][testimonial]. =)
 
@@ -125,6 +334,7 @@ Are you using this project or any of our other projects? Consider [leaving a tes
 
 Check out these related projects.
 
+- [github-action-matrix-outputs-write](https://github.com/cloudposse/github-action-matrix-outputs-write) - Matrix outputs write
 
 
 ## References
@@ -139,7 +349,7 @@ For additional context, refer to some of these links.
 
 **Got a question?** We got answers.
 
-File a GitHub [issue](https://github.com/cloudposse/example-github-action-composite/issues), send us an [email][email] or join our [Slack Community][slack].
+File a GitHub [issue](https://github.com/cloudposse/github-action-matrix-outputs-read/issues), send us an [email][email] or join our [Slack Community][slack].
 
 [![README Commercial Support][readme_commercial_support_img]][readme_commercial_support_link]
 
@@ -187,7 +397,7 @@ Sign up for [our newsletter][newsletter] that covers everything on our technolog
 
 ### Bug Reports & Feature Requests
 
-Please use the [issue tracker](https://github.com/cloudposse/example-github-action-composite/issues) to report any bugs or file feature requests.
+Please use the [issue tracker](https://github.com/cloudposse/github-action-matrix-outputs-read/issues) to report any bugs or file feature requests.
 
 ### Developing
 
@@ -275,33 +485,33 @@ Check out [our other projects][github], [follow us on twitter][twitter], [apply
 [![Beacon][beacon]][website]
 <!-- markdownlint-disable -->
   [logo]: https://cloudposse.com/logo-300x69.svg
-  [docs]: https://cpco.io/docs?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=docs
-  [website]: https://cpco.io/homepage?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=website
-  [github]: https://cpco.io/github?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=github
-  [jobs]: https://cpco.io/jobs?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=jobs
-  [hire]: https://cpco.io/hire?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=hire
-  [slack]: https://cpco.io/slack?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=slack
-  [linkedin]: https://cpco.io/linkedin?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=linkedin
-  [twitter]: https://cpco.io/twitter?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=twitter
-  [testimonial]: https://cpco.io/leave-testimonial?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=testimonial
-  [office_hours]: https://cloudposse.com/office-hours?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=office_hours
-  [newsletter]: https://cpco.io/newsletter?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=newsletter
-  [discourse]: https://ask.sweetops.com/?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=discourse
-  [email]: https://cpco.io/email?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=email
-  [commercial_support]: https://cpco.io/commercial-support?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=commercial_support
-  [we_love_open_source]: https://cpco.io/we-love-open-source?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=we_love_open_source
-  [terraform_modules]: https://cpco.io/terraform-modules?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=terraform_modules
+  [docs]: https://cpco.io/docs?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=docs
+  [website]: https://cpco.io/homepage?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=website
+  [github]: https://cpco.io/github?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=github
+  [jobs]: https://cpco.io/jobs?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=jobs
+  [hire]: https://cpco.io/hire?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=hire
+  [slack]: https://cpco.io/slack?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=slack
+  [linkedin]: https://cpco.io/linkedin?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=linkedin
+  [twitter]: https://cpco.io/twitter?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=twitter
+  [testimonial]: https://cpco.io/leave-testimonial?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=testimonial
+  [office_hours]: https://cloudposse.com/office-hours?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=office_hours
+  [newsletter]: https://cpco.io/newsletter?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=newsletter
+  [discourse]: https://ask.sweetops.com/?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=discourse
+  [email]: https://cpco.io/email?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=email
+  [commercial_support]: https://cpco.io/commercial-support?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=commercial_support
+  [we_love_open_source]: https://cpco.io/we-love-open-source?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=we_love_open_source
+  [terraform_modules]: https://cpco.io/terraform-modules?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=terraform_modules
   [readme_header_img]: https://cloudposse.com/readme/header/img
-  [readme_header_link]: https://cloudposse.com/readme/header/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=readme_header_link
+  [readme_header_link]: https://cloudposse.com/readme/header/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=readme_header_link
   [readme_footer_img]: https://cloudposse.com/readme/footer/img
-  [readme_footer_link]: https://cloudposse.com/readme/footer/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=readme_footer_link
+  [readme_footer_link]: https://cloudposse.com/readme/footer/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=readme_footer_link
   [readme_commercial_support_img]: https://cloudposse.com/readme/commercial-support/img
-  [readme_commercial_support_link]: https://cloudposse.com/readme/commercial-support/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=readme_commercial_support_link
-  [share_twitter]: https://twitter.com/intent/tweet/?text=example-github-action-composite&url=https://github.com/cloudposse/example-github-action-composite
-  [share_linkedin]: https://www.linkedin.com/shareArticle?mini=true&title=example-github-action-composite&url=https://github.com/cloudposse/example-github-action-composite
-  [share_reddit]: https://reddit.com/submit/?url=https://github.com/cloudposse/example-github-action-composite
-  [share_facebook]: https://facebook.com/sharer/sharer.php?u=https://github.com/cloudposse/example-github-action-composite
-  [share_googleplus]: https://plus.google.com/share?url=https://github.com/cloudposse/example-github-action-composite
-  [share_email]: mailto:?subject=example-github-action-composite&body=https://github.com/cloudposse/example-github-action-composite
-  [beacon]: https://ga-beacon.cloudposse.com/UA-76589703-4/cloudposse/example-github-action-composite?pixel&cs=github&cm=readme&an=example-github-action-composite
+  [readme_commercial_support_link]: https://cloudposse.com/readme/commercial-support/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-read&utm_content=readme_commercial_support_link
+  [share_twitter]: https://twitter.com/intent/tweet/?text=github-action-matrix-outputs-read&url=https://github.com/cloudposse/github-action-matrix-outputs-read
+  [share_linkedin]: https://www.linkedin.com/shareArticle?mini=true&title=github-action-matrix-outputs-read&url=https://github.com/cloudposse/github-action-matrix-outputs-read
+  [share_reddit]: https://reddit.com/submit/?url=https://github.com/cloudposse/github-action-matrix-outputs-read
+  [share_facebook]: https://facebook.com/sharer/sharer.php?u=https://github.com/cloudposse/github-action-matrix-outputs-read
+  [share_googleplus]: https://plus.google.com/share?url=https://github.com/cloudposse/github-action-matrix-outputs-read
+  [share_email]: mailto:?subject=github-action-matrix-outputs-read&body=https://github.com/cloudposse/github-action-matrix-outputs-read
+  [beacon]: https://ga-beacon.cloudposse.com/UA-76589703-4/cloudposse/github-action-matrix-outputs-read?pixel&cs=github&cm=readme&an=github-action-matrix-outputs-read
 <!-- markdownlint-restore -->