Skip to content

Commit 199a58f

Browse files
robherleyrobherley
committed
more docs
1 parent 3f353f9 commit 199a58f

File tree

2 files changed

+200
-1
lines changed

2 files changed

+200
-1
lines changed

‎docs/MIGRATION.md

+62
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
- [Migration](#migration)
44
- [Multiple uploads to the same named Artifact](#multiple-uploads-to-the-same-named-artifact)
55
- [Overwriting an Artifact](#overwriting-an-artifact)
6+
- [Merging multiple artifacts](#merging-multiple-artifacts)
67

78
Several behavioral differences exist between Artifact actions `v3` and below vs `v4`. This document outlines common scenarios in `v3`, and how they would be handled in `v4`.
89

@@ -142,3 +143,64 @@ jobs:
142143
```
143144

144145
Note that this will create an _entirely_ new Artifact, with a different ID from the previous.
146+
147+
## Merging multiple artifacts
148+
149+
In `v3`, multiple uploads from multiple jobs could be done to the same Artifact. This would result in a single archive, which could be useful for sending to upstream systems outside of Actions via API or UI downloads.
150+
151+
```yaml
152+
jobs:
153+
upload:
154+
strategy:
155+
matrix:
156+
runs-on: [ubuntu-latest, macos-latest, windows-latest]
157+
runs-on: ${{ matrix.runs-on }}
158+
steps:
159+
- name: Create a File
160+
run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
161+
- name: Upload Artifact
162+
uses: actions/upload-artifact@v3
163+
with:
164+
name: all-my-files # NOTE: same artifact name
165+
path: file-${{ matrix.runs-on }}.txt
166+
```
167+
168+
The single `all-my-files` artifact would contain the following:
169+
170+
```
171+
.
172+
∟ file-ubuntu-latest.txt
173+
∟ file-macos-latest.txt
174+
∟ file-windows-latest.txt
175+
```
176+
177+
To achieve the same in `v4` you can change it like so:
178+
179+
```diff
180+
jobs:
181+
upload:
182+
strategy:
183+
matrix:
184+
runs-on: [ubuntu-latest, macos-latest, windows-latest]
185+
runs-on: ${{ matrix.runs-on }}
186+
steps:
187+
- name: Create a File
188+
run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
189+
- name: Upload Artifact
190+
uses: actions/upload-artifact@v3
191+
with:
192+
- name: all-my-files
193+
+ name: my-artifact-${{ matrix.runs-on }}
194+
path: file-${{ matrix.runs-on }}.txt
195+
+ merge:
196+
+ runs-on: ubuntu-latest
197+
+ needs: upload
198+
+ steps:
199+
+ - name: Merge Artifacts
200+
+ uses: actions/upload-artifact/merge@v4
201+
+ with:
202+
+ name: all-my-files
203+
+ pattern: my-artifact-*
204+
```
205+
206+
Note that this will download all artifacts to a temporary directory and reupload them as a single artifact. For more information on inputs and other use cases for `actions/upload-artifact/merge@v4`, see [the action documentation](../merge/README.md).

‎merge/README.md

+138-1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@ Merge multiple [Actions Artifacts](https://docs.github.com/en/actions/using-work
77
- [Inputs](#inputs)
88
- [Outputs](#outputs)
99
- [Examples](#examples)
10+
- [Combining all artifacts in a workflow run](#combining-all-artifacts-in-a-workflow-run)
11+
- [Prefix directories in merged artifact](#prefix-directories-in-merged-artifact)
12+
- [Deleting artifacts after merge](#deleting-artifacts-after-merge)
13+
- [Retention and Compression Level](#retention-and-compression-level)
1014

1115
## Usage
1216

@@ -15,6 +19,10 @@ Merge multiple [Actions Artifacts](https://docs.github.com/en/actions/using-work
1519
1620
Note: this actions can only merge artifacts created with actions/upload-artifact@v4+
1721

22+
This sub-action is a helper to merge multiple artifacts after they are created. To do so, it will download multiple artifacts to a temporary directory and reupload them as a single artifact.
23+
24+
For most cases, this may not be the most efficient solution. See [the migration docs](../docs/MIGRATION.md#multiple-uploads-to-the-same-named-artifact) on how to download multiple artifacts to the same directory on a runner. This action should only be necessary for cases where multiple artifacts will need to be downloaded outside the runner environment, like downloads via the UI or REST API.
25+
1826
### Inputs
1927

2028
```yaml
@@ -60,4 +68,133 @@ Note: this actions can only merge artifacts created with actions/upload-artifact
6068

6169
## Examples
6270

63-
TODO(robherley): add examples
71+
For each of these examples, assume we have a prior job matrix that generates three artifacts: `my-artifact-a`, `my-artifact-b` and `my-artifact-c`.
72+
73+
e.g.
74+
75+
```yaml
76+
jobs:
77+
upload:
78+
runs-on: ubuntu-latest
79+
80+
strategy:
81+
matrix:
82+
foo: [a, b, c]
83+
84+
steps:
85+
- name: Run a one-line script
86+
run: echo "hello from job ${{ matrix.foo }}" > file-${{ matrix.foo }}.txt
87+
- name: Upload
88+
uses: actions/upload-artifact@v4
89+
with:
90+
name: my-artifact-${{ matrix.foo }}
91+
path: file-${{ matrix.foo }}.txt
92+
```
93+
94+
Each of the following examples will use the `needs: upload` as a prerequesite before any merging operations.
95+
96+
### Combining all artifacts in a workflow run
97+
98+
By default (with no inputs), calling this action will take all the artifacts in the workflow run and combined them into a single artifact called `merged-artifacts`:
99+
100+
```yaml
101+
jobs:
102+
# ... <upload job> ...
103+
merge:
104+
runs-on: ubuntu-latest
105+
needs: upload
106+
steps:
107+
- name: Merge Artifacts
108+
uses: actions/upload-artifact/merge@v4
109+
```
110+
111+
This will result in an artifact called `merged-artifacts` with the following content:
112+
113+
```
114+
.
115+
∟ file-a.txt
116+
∟ file-b.txt
117+
∟ file-c.txt
118+
```
119+
120+
To change the name of the artifact and filter on what artifacts are added, you can use the `name` and `pattern` inputs:
121+
122+
```yaml
123+
jobs:
124+
# ... <upload job> ...
125+
merge:
126+
runs-on: ubuntu-latest
127+
needs: upload
128+
steps:
129+
- name: Merge Artifacts
130+
uses: actions/upload-artifact/merge@v4
131+
with:
132+
name: my-amazing-merged-artifact
133+
pattern: my-artifact-*
134+
```
135+
136+
### Prefix directories in merged artifact
137+
138+
To prevent overwriting files in artifacts that may have the same name, you can use the `separate-directories` to prefix the extracted files with directories (named after the original artifact):
139+
140+
```yaml
141+
jobs:
142+
# ... <upload job> ...
143+
merge:
144+
runs-on: ubuntu-latest
145+
needs: upload
146+
steps:
147+
- name: Merge Artifacts
148+
uses: actions/upload-artifact/merge@v4
149+
with:
150+
separate-directories: true
151+
```
152+
153+
This will result in the following artifact structure:
154+
155+
```
156+
.
157+
∟ my-artifact-a
158+
∟ file-a.txt
159+
∟ my-artifact-b
160+
∟ file-b.txt
161+
∟ my-artifact-c
162+
∟ file-c.txt
163+
```
164+
165+
### Deleting artifacts after merge
166+
167+
After merge, the old artifacts may no longer be required. To automatically delete them after they are merged into a new artifact, you can use `delete-merged` like so:
168+
169+
```yaml
170+
jobs:
171+
# ... <upload job> ...
172+
merge:
173+
runs-on: ubuntu-latest
174+
needs: upload
175+
steps:
176+
- name: Merge Artifacts
177+
uses: actions/upload-artifact/merge@v4
178+
with:
179+
delete-merged: true
180+
```
181+
182+
After this runs, the matching artifact (`my-artifact-a`, `my-artifact-b` and `my-artifact-c`) will be merged.
183+
184+
### Retention and Compression Level
185+
186+
Similar to actions/upload-artifact, both [`retention-days`](../README.md#retention-period) and [`compression-level`](../README.md#altering-compressions-level-speed-v-size) are supported:
187+
188+
```yaml
189+
jobs:
190+
# ... <upload job> ...
191+
merge:
192+
runs-on: ubuntu-latest
193+
needs: upload
194+
steps:
195+
- name: Merge Artifacts
196+
uses: actions/upload-artifact/merge@v4
197+
with:
198+
retention-days: 1
199+
compression-level: 9
200+
```

0 commit comments

Comments
 (0)