Skip to content

Commit

Permalink
Update README.md and docs (#13)
Browse files Browse the repository at this point in the history 
Co-authored-by: goruha <goruha@users.noreply.github.com>
  • Loading branch information
@cloudpossebot @goruha
cloudpossebot and goruha authored Dec 8, 2022
1 parent 0d965be commit ea1c28d
Showing 1 changed file with 249 additions and 39 deletions.
288 changes: 249 additions & 39 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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]
Expand Down Expand Up @@ -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


---

Expand Down Expand Up @@ -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)



Expand All @@ -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:
Expand All @@ -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 }}
```


Expand Down Expand Up @@ -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]. =)

Expand All @@ -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
Expand All @@ -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]

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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 -->

0 comments on commit ea1c28d

Please sign in to comment.