Skip to content

Commit 37370c6

Browse files
cloudpossebotgoruha
cloudpossebot
and
goruha
authored
Update README.md and docs (#10)
Co-authored-by: goruha <[email protected]>
1 parent c0aec78 commit 37370c6

File tree

1 file changed

+246
-39
lines changed

1 file changed

+246
-39
lines changed

‎README.md

Lines changed: 246 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11

22
<!-- markdownlint-disable -->
3-
# 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)
3+
# github-action-matrix-outputs-write [![Latest Release](https://img.shields.io/github/release/cloudposse/github-action-matrix-outputs-write.svg)](https://github.com/cloudposse/github-action-matrix-outputs-write/releases/latest) [![Slack Community](https://slack.cloudposse.com/badge.svg)](https://slack.cloudposse.com)
44
<!-- markdownlint-restore -->
55

66
[![README Header][readme_header_img]][readme_header_link]
@@ -28,7 +28,8 @@
2828
2929
-->
3030

31-
Template repository of composite GitHub Action
31+
[Workaround implementation](https://github.com/community/community/discussions/17245#discussioncomment-3814009) - Write matrix jobs outputs
32+
3233

3334
---
3435

@@ -58,8 +59,14 @@ It's 100% Open Source and licensed under the [APACHE2](LICENSE).
5859

5960
## Introduction
6061

61-
This is template repository to create composite GitHub Actions.
62-
Feel free to use it as reference and starting point.
62+
GitHub actions have an [Jobs need a way to reference all outputs of matrix jobs](https://github.com/community/community/discussions/17245) issue.
63+
If there is a job that runs multiple times with `strategy.matrix` only the latest iteration's output availiable for
64+
reference in other jobs.
65+
66+
There is a [workaround](https://github.com/community/community/discussions/17245#discussioncomment-3814009) to address the limitation.
67+
We implement the workaround with two GitHub Actions:
68+
* [Matrix Outputs Write](https://github.com/cloudposse/github-action-matrix-outputs-write)
69+
* [Matrix Outputs Read](https://github.com/cloudposse/github-action-matrix-outputs-read)
6370

6471

6572

@@ -69,6 +76,8 @@ Feel free to use it as reference and starting point.
6976

7077

7178

79+
Example how you can use workaround to reference matrix job outputs.
80+
7281
```yaml
7382
name: Pull Request
7483
on:
@@ -77,17 +86,214 @@ Feel free to use it as reference and starting point.
7786
types: [opened, synchronize, reopened, closed, labeled, unlabeled]
7887

7988
jobs:
80-
context:
89+
build:
90+
runs-on: ubuntu-latest
91+
strategy:
92+
matrix:
93+
platform: ["i386", "arm64v8"]
94+
steps:
95+
- name: Checkout
96+
uses: actions/checkout@v3
97+
98+
- name: Build
99+
id: build
100+
uses: cloudposse/[email protected]
101+
with:
102+
registry: registry.hub.docker.com
103+
organization: "${{ github.event.repository.owner.login }}"
104+
repository: "${{ github.event.repository.name }}"
105+
build-args: |-
106+
PLATFORM=${{ matrix.platform }}
107+
108+
## Write for matrix outputs workaround
109+
- uses: cloudposse/github-action-matrix-outputs-write@main
110+
id: out
111+
with:
112+
matrix-step-name: ${{ github.job }}
113+
matrix-key: ${{ matrix.platform }}
114+
outputs: |-
115+
image: ${{ steps.build.outputs.image }}:${{ steps.build.outputs.tag }}
116+
117+
## Read matrix outputs
118+
read:
81119
runs-on: ubuntu-latest
120+
needs: [build]
82121
steps:
83-
- name: Example action
84-
uses: cloudposse/example-github-action-composite@main
85-
id: example
122+
- uses: cloudposse/github-action-matrix-outputs-read@main
123+
id: read
86124
with:
87-
param1: true
125+
matrix-step-name: build
88126

89127
outputs:
90-
result: ${{ steps.example.outputs.result1 }}
128+
result: "${{ steps.read.outputs.result }}"
129+
130+
## This how you can reference matrix output
131+
assert:
132+
runs-on: ubuntu-latest
133+
needs: [read]
134+
steps:
135+
- uses: nick-fields/assert-action@v1
136+
with:
137+
expected: ${{ registry.hub.docker.com }}/${{ github.event.repository.owner.login }}/${{ github.event.repository.name }}:i386
138+
## This how you can reference matrix output
139+
actual: ${{ fromJson(needs.read.outputs.result).image.i386 }}
140+
141+
- uses: nick-fields/assert-action@v1
142+
with:
143+
expected: ${{ registry.hub.docker.com }}/${{ github.event.repository.owner.login }}/${{ github.event.repository.name }}:arm64v8
144+
## This how you can reference matrix output
145+
actual: ${{ fromJson(needs.read.outputs.result).image.arm64v8 }}
146+
```
147+
148+
### Reusable workflow example
149+
150+
Reusable workflow that support matrix outputs
151+
`./.github/workflow/build-reusabled.yaml`
152+
```yaml
153+
name: Build - Reusable workflow
154+
on:
155+
workflow_call:
156+
inputs:
157+
registry:
158+
required: true
159+
type: string
160+
organization:
161+
required: true
162+
type: string
163+
repository:
164+
required: true
165+
type: string
166+
platform:
167+
required: true
168+
type: string
169+
matrix-step-name:
170+
required: false
171+
type: string
172+
matrix-key:
173+
required: false
174+
type: string
175+
outputs:
176+
image:
177+
description: "Image"
178+
value: ${{ jobs.write.outputs.image }}
179+
180+
jobs:
181+
build:
182+
runs-on: ubuntu-latest
183+
steps:
184+
- name: Checkout
185+
uses: actions/checkout@v3
186+
187+
- name: Build
188+
id: build
189+
uses: cloudposse/[email protected]
190+
with:
191+
registry: ${{ inputs.registry }}
192+
organization: ${{ inputs.organization }}
193+
repository: ${{ inputs.repository }}
194+
build-args: |-
195+
PLATFORM=${{ inputs.platform }}
196+
outputs:
197+
image: ${{ needs.build.outputs.image }}:${{ needs.build.outputs.tag }}
198+
199+
write:
200+
runs-on: ubuntu-latest
201+
needs: [build]
202+
steps:
203+
## Write for matrix outputs workaround
204+
- uses: cloudposse/github-action-matrix-outputs-write@main
205+
id: out
206+
with:
207+
matrix-step-name: ${{ inputs.matrix-step-name }}
208+
matrix-key: ${{ inputs.matrix-key }}
209+
outputs: |-
210+
image: ${{ needs.build.outputs.image }}
211+
212+
outputs:
213+
image: ${{ fromJson(steps.out.outputs.result).image }}
214+
```
215+
216+
Then you can use the workflow with matrix
217+
```
218+
name: Pull Request
219+
on:
220+
pull_request:
221+
branches: [ 'main' ]
222+
types: [opened, synchronize, reopened, closed, labeled, unlabeled]
223+
224+
jobs:
225+
build:
226+
usage: ./.github/workflow/build-reusabled.yaml
227+
strategy:
228+
matrix:
229+
platform: ["i386", "arm64v8"]
230+
with:
231+
registry: registry.hub.docker.com
232+
organization: "${{ github.event.repository.owner.login }}"
233+
repository: "${{ github.event.repository.name }}"
234+
platform: ${{ matrix.platform }}
235+
matrix-step-name: ${{ github.job }}
236+
matrix-key: ${{ matrix.platform }}
237+
238+
## Read matrix outputs
239+
read:
240+
runs-on: ubuntu-latest
241+
needs: [build]
242+
steps:
243+
- uses: cloudposse/github-action-matrix-outputs-read@main
244+
id: read
245+
with:
246+
matrix-step-name: build
247+
248+
outputs:
249+
result: "${{ steps.read.outputs.result }}"
250+
251+
## This how you can reference matrix output
252+
assert:
253+
runs-on: ubuntu-latest
254+
needs: [read]
255+
steps:
256+
- uses: nick-fields/assert-action@v1
257+
with:
258+
expected: ${{ registry.hub.docker.com }}/${{ github.event.repository.owner.login }}/${{ github.event.repository.name }}:i386
259+
## This how you can reference matrix output
260+
actual: ${{ fromJson(needs.read.outputs.result).image.i386 }}
261+
262+
- uses: nick-fields/assert-action@v1
263+
with:
264+
expected: ${{ registry.hub.docker.com }}/${{ github.event.repository.owner.login }}/${{ github.event.repository.name }}:arm64v8
265+
## This how you can reference matrix output
266+
actual: ${{ fromJson(needs.read.outputs.result).image.arm64v8 }}
267+
```
268+
269+
or as a simple job
270+
271+
```yaml
272+
name: Pull Request
273+
on:
274+
pull_request:
275+
branches: [ 'main' ]
276+
types: [opened, synchronize, reopened, closed, labeled, unlabeled]
277+
278+
jobs:
279+
build:
280+
usage: ./.github/workflow/build-reusabled.yaml
281+
with:
282+
registry: registry.hub.docker.com
283+
organization: "${{ github.event.repository.owner.login }}"
284+
repository: "${{ github.event.repository.name }}"
285+
platform: "i386"
286+
287+
## This how you can reference single job output
288+
assert:
289+
runs-on: ubuntu-latest
290+
needs: [build]
291+
steps:
292+
- uses: nick-fields/assert-action@v1
293+
with:
294+
expected: ${{ registry.hub.docker.com }}/${{ github.event.repository.owner.login }}/${{ github.event.repository.name }}:i386
295+
## This how you can reference matrix output
296+
actual: ${{ needs.build.outputs.image }}
91297
```
92298

93299

@@ -117,7 +323,7 @@ Feel free to use it as reference and starting point.
117323

118324
## Share the Love
119325

120-
Like this project? Please give it a ★ on [our GitHub](https://github.com/cloudposse/example-github-action-composite)! (it helps us **a lot**)
326+
Like this project? Please give it a ★ on [our GitHub](https://github.com/cloudposse/github-action-matrix-outputs-write)! (it helps us **a lot**)
121327

122328
Are you using this project or any of our other projects? Consider [leaving a testimonial][testimonial]. =)
123329

@@ -127,6 +333,7 @@ Are you using this project or any of our other projects? Consider [leaving a tes
127333

128334
Check out these related projects.
129335

336+
- [github-action-matrix-outputs-read](https://github.com/cloudposse/github-action-matrix-outputs-write) - Matrix outputs read
130337

131338

132339
## References
@@ -141,7 +348,7 @@ For additional context, refer to some of these links.
141348

142349
**Got a question?** We got answers.
143350

144-
File a GitHub [issue](https://github.com/cloudposse/example-github-action-composite/issues), send us an [email][email] or join our [Slack Community][slack].
351+
File a GitHub [issue](https://github.com/cloudposse/github-action-matrix-outputs-write/issues), send us an [email][email] or join our [Slack Community][slack].
145352

146353
[![README Commercial Support][readme_commercial_support_img]][readme_commercial_support_link]
147354

@@ -189,7 +396,7 @@ Sign up for [our newsletter][newsletter] that covers everything on our technolog
189396

190397
### Bug Reports & Feature Requests
191398

192-
Please use the [issue tracker](https://github.com/cloudposse/example-github-action-composite/issues) to report any bugs or file feature requests.
399+
Please use the [issue tracker](https://github.com/cloudposse/github-action-matrix-outputs-write/issues) to report any bugs or file feature requests.
193400

194401
### Developing
195402

@@ -277,33 +484,33 @@ Check out [our other projects][github], [follow us on twitter][twitter], [apply
277484
[![Beacon][beacon]][website]
278485
<!-- markdownlint-disable -->
279486
[logo]: https://cloudposse.com/logo-300x69.svg
280-
[docs]: https://cpco.io/docs?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=docs
281-
[website]: https://cpco.io/homepage?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=website
282-
[github]: https://cpco.io/github?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=github
283-
[jobs]: https://cpco.io/jobs?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=jobs
284-
[hire]: https://cpco.io/hire?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=hire
285-
[slack]: https://cpco.io/slack?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=slack
286-
[linkedin]: https://cpco.io/linkedin?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=linkedin
287-
[twitter]: https://cpco.io/twitter?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=twitter
288-
[testimonial]: https://cpco.io/leave-testimonial?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=testimonial
289-
[office_hours]: https://cloudposse.com/office-hours?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=office_hours
290-
[newsletter]: https://cpco.io/newsletter?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=newsletter
291-
[discourse]: https://ask.sweetops.com/?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=discourse
292-
[email]: https://cpco.io/email?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=email
293-
[commercial_support]: https://cpco.io/commercial-support?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=commercial_support
294-
[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
295-
[terraform_modules]: https://cpco.io/terraform-modules?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/example-github-action-composite&utm_content=terraform_modules
487+
[docs]: https://cpco.io/docs?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=docs
488+
[website]: https://cpco.io/homepage?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=website
489+
[github]: https://cpco.io/github?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=github
490+
[jobs]: https://cpco.io/jobs?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=jobs
491+
[hire]: https://cpco.io/hire?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=hire
492+
[slack]: https://cpco.io/slack?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=slack
493+
[linkedin]: https://cpco.io/linkedin?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=linkedin
494+
[twitter]: https://cpco.io/twitter?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=twitter
495+
[testimonial]: https://cpco.io/leave-testimonial?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=testimonial
496+
[office_hours]: https://cloudposse.com/office-hours?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=office_hours
497+
[newsletter]: https://cpco.io/newsletter?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=newsletter
498+
[discourse]: https://ask.sweetops.com/?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=discourse
499+
[email]: https://cpco.io/email?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=email
500+
[commercial_support]: https://cpco.io/commercial-support?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=commercial_support
501+
[we_love_open_source]: https://cpco.io/we-love-open-source?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=we_love_open_source
502+
[terraform_modules]: https://cpco.io/terraform-modules?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=terraform_modules
296503
[readme_header_img]: https://cloudposse.com/readme/header/img
297-
[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
504+
[readme_header_link]: https://cloudposse.com/readme/header/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=readme_header_link
298505
[readme_footer_img]: https://cloudposse.com/readme/footer/img
299-
[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
506+
[readme_footer_link]: https://cloudposse.com/readme/footer/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=readme_footer_link
300507
[readme_commercial_support_img]: https://cloudposse.com/readme/commercial-support/img
301-
[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
302-
[share_twitter]: https://twitter.com/intent/tweet/?text=example-github-action-composite&url=https://github.com/cloudposse/example-github-action-composite
303-
[share_linkedin]: https://www.linkedin.com/shareArticle?mini=true&title=example-github-action-composite&url=https://github.com/cloudposse/example-github-action-composite
304-
[share_reddit]: https://reddit.com/submit/?url=https://github.com/cloudposse/example-github-action-composite
305-
[share_facebook]: https://facebook.com/sharer/sharer.php?u=https://github.com/cloudposse/example-github-action-composite
306-
[share_googleplus]: https://plus.google.com/share?url=https://github.com/cloudposse/example-github-action-composite
307-
[share_email]: mailto:?subject=example-github-action-composite&body=https://github.com/cloudposse/example-github-action-composite
308-
[beacon]: https://ga-beacon.cloudposse.com/UA-76589703-4/cloudposse/example-github-action-composite?pixel&cs=github&cm=readme&an=example-github-action-composite
508+
[readme_commercial_support_link]: https://cloudposse.com/readme/commercial-support/link?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/github-action-matrix-outputs-write&utm_content=readme_commercial_support_link
509+
[share_twitter]: https://twitter.com/intent/tweet/?text=github-action-matrix-outputs-write&url=https://github.com/cloudposse/github-action-matrix-outputs-write
510+
[share_linkedin]: https://www.linkedin.com/shareArticle?mini=true&title=github-action-matrix-outputs-write&url=https://github.com/cloudposse/github-action-matrix-outputs-write
511+
[share_reddit]: https://reddit.com/submit/?url=https://github.com/cloudposse/github-action-matrix-outputs-write
512+
[share_facebook]: https://facebook.com/sharer/sharer.php?u=https://github.com/cloudposse/github-action-matrix-outputs-write
513+
[share_googleplus]: https://plus.google.com/share?url=https://github.com/cloudposse/github-action-matrix-outputs-write
514+
[share_email]: mailto:?subject=github-action-matrix-outputs-write&body=https://github.com/cloudposse/github-action-matrix-outputs-write
515+
[beacon]: https://ga-beacon.cloudposse.com/UA-76589703-4/cloudposse/github-action-matrix-outputs-write?pixel&cs=github&cm=readme&an=github-action-matrix-outputs-write
309516
<!-- markdownlint-restore -->

0 commit comments

Comments
 (0)