mirror of
https://code.forgejo.org/actions/upload-artifact.git
synced 2024-12-23 04:06:00 +01:00
more docs
This commit is contained in:
parent
3f353f9d9e
commit
199a58f54f
2 changed files with 200 additions and 1 deletions
|
@ -3,6 +3,7 @@
|
||||||
- [Migration](#migration)
|
- [Migration](#migration)
|
||||||
- [Multiple uploads to the same named Artifact](#multiple-uploads-to-the-same-named-artifact)
|
- [Multiple uploads to the same named Artifact](#multiple-uploads-to-the-same-named-artifact)
|
||||||
- [Overwriting an Artifact](#overwriting-an-artifact)
|
- [Overwriting an Artifact](#overwriting-an-artifact)
|
||||||
|
- [Merging multiple artifacts](#merging-multiple-artifacts)
|
||||||
|
|
||||||
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`.
|
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`.
|
||||||
|
|
||||||
|
@ -142,3 +143,64 @@ jobs:
|
||||||
```
|
```
|
||||||
|
|
||||||
Note that this will create an _entirely_ new Artifact, with a different ID from the previous.
|
Note that this will create an _entirely_ new Artifact, with a different ID from the previous.
|
||||||
|
|
||||||
|
## Merging multiple artifacts
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
jobs:
|
||||||
|
upload:
|
||||||
|
strategy:
|
||||||
|
matrix:
|
||||||
|
runs-on: [ubuntu-latest, macos-latest, windows-latest]
|
||||||
|
runs-on: ${{ matrix.runs-on }}
|
||||||
|
steps:
|
||||||
|
- name: Create a File
|
||||||
|
run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
|
||||||
|
- name: Upload Artifact
|
||||||
|
uses: actions/upload-artifact@v3
|
||||||
|
with:
|
||||||
|
name: all-my-files # NOTE: same artifact name
|
||||||
|
path: file-${{ matrix.runs-on }}.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
The single `all-my-files` artifact would contain the following:
|
||||||
|
|
||||||
|
```
|
||||||
|
.
|
||||||
|
∟ file-ubuntu-latest.txt
|
||||||
|
∟ file-macos-latest.txt
|
||||||
|
∟ file-windows-latest.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
To achieve the same in `v4` you can change it like so:
|
||||||
|
|
||||||
|
```diff
|
||||||
|
jobs:
|
||||||
|
upload:
|
||||||
|
strategy:
|
||||||
|
matrix:
|
||||||
|
runs-on: [ubuntu-latest, macos-latest, windows-latest]
|
||||||
|
runs-on: ${{ matrix.runs-on }}
|
||||||
|
steps:
|
||||||
|
- name: Create a File
|
||||||
|
run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
|
||||||
|
- name: Upload Artifact
|
||||||
|
uses: actions/upload-artifact@v3
|
||||||
|
with:
|
||||||
|
- name: all-my-files
|
||||||
|
+ name: my-artifact-${{ matrix.runs-on }}
|
||||||
|
path: file-${{ matrix.runs-on }}.txt
|
||||||
|
+ merge:
|
||||||
|
+ runs-on: ubuntu-latest
|
||||||
|
+ needs: upload
|
||||||
|
+ steps:
|
||||||
|
+ - name: Merge Artifacts
|
||||||
|
+ uses: actions/upload-artifact/merge@v4
|
||||||
|
+ with:
|
||||||
|
+ name: all-my-files
|
||||||
|
+ pattern: my-artifact-*
|
||||||
|
```
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
139
merge/README.md
139
merge/README.md
|
@ -7,6 +7,10 @@ Merge multiple [Actions Artifacts](https://docs.github.com/en/actions/using-work
|
||||||
- [Inputs](#inputs)
|
- [Inputs](#inputs)
|
||||||
- [Outputs](#outputs)
|
- [Outputs](#outputs)
|
||||||
- [Examples](#examples)
|
- [Examples](#examples)
|
||||||
|
- [Combining all artifacts in a workflow run](#combining-all-artifacts-in-a-workflow-run)
|
||||||
|
- [Prefix directories in merged artifact](#prefix-directories-in-merged-artifact)
|
||||||
|
- [Deleting artifacts after merge](#deleting-artifacts-after-merge)
|
||||||
|
- [Retention and Compression Level](#retention-and-compression-level)
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
|
@ -15,6 +19,10 @@ Merge multiple [Actions Artifacts](https://docs.github.com/en/actions/using-work
|
||||||
|
|
||||||
Note: this actions can only merge artifacts created with actions/upload-artifact@v4+
|
Note: this actions can only merge artifacts created with actions/upload-artifact@v4+
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
### Inputs
|
### Inputs
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
|
@ -60,4 +68,133 @@ Note: this actions can only merge artifacts created with actions/upload-artifact
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
|
|
||||||
TODO(robherley): add examples
|
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`.
|
||||||
|
|
||||||
|
e.g.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
jobs:
|
||||||
|
upload:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
|
||||||
|
strategy:
|
||||||
|
matrix:
|
||||||
|
foo: [a, b, c]
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- name: Run a one-line script
|
||||||
|
run: echo "hello from job ${{ matrix.foo }}" > file-${{ matrix.foo }}.txt
|
||||||
|
- name: Upload
|
||||||
|
uses: actions/upload-artifact@v4
|
||||||
|
with:
|
||||||
|
name: my-artifact-${{ matrix.foo }}
|
||||||
|
path: file-${{ matrix.foo }}.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
Each of the following examples will use the `needs: upload` as a prerequesite before any merging operations.
|
||||||
|
|
||||||
|
### Combining all artifacts in a workflow run
|
||||||
|
|
||||||
|
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`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
jobs:
|
||||||
|
# ... <upload job> ...
|
||||||
|
merge:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
needs: upload
|
||||||
|
steps:
|
||||||
|
- name: Merge Artifacts
|
||||||
|
uses: actions/upload-artifact/merge@v4
|
||||||
|
```
|
||||||
|
|
||||||
|
This will result in an artifact called `merged-artifacts` with the following content:
|
||||||
|
|
||||||
|
```
|
||||||
|
.
|
||||||
|
∟ file-a.txt
|
||||||
|
∟ file-b.txt
|
||||||
|
∟ file-c.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
To change the name of the artifact and filter on what artifacts are added, you can use the `name` and `pattern` inputs:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
jobs:
|
||||||
|
# ... <upload job> ...
|
||||||
|
merge:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
needs: upload
|
||||||
|
steps:
|
||||||
|
- name: Merge Artifacts
|
||||||
|
uses: actions/upload-artifact/merge@v4
|
||||||
|
with:
|
||||||
|
name: my-amazing-merged-artifact
|
||||||
|
pattern: my-artifact-*
|
||||||
|
```
|
||||||
|
|
||||||
|
### Prefix directories in merged artifact
|
||||||
|
|
||||||
|
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):
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
jobs:
|
||||||
|
# ... <upload job> ...
|
||||||
|
merge:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
needs: upload
|
||||||
|
steps:
|
||||||
|
- name: Merge Artifacts
|
||||||
|
uses: actions/upload-artifact/merge@v4
|
||||||
|
with:
|
||||||
|
separate-directories: true
|
||||||
|
```
|
||||||
|
|
||||||
|
This will result in the following artifact structure:
|
||||||
|
|
||||||
|
```
|
||||||
|
.
|
||||||
|
∟ my-artifact-a
|
||||||
|
∟ file-a.txt
|
||||||
|
∟ my-artifact-b
|
||||||
|
∟ file-b.txt
|
||||||
|
∟ my-artifact-c
|
||||||
|
∟ file-c.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
### Deleting artifacts after merge
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
jobs:
|
||||||
|
# ... <upload job> ...
|
||||||
|
merge:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
needs: upload
|
||||||
|
steps:
|
||||||
|
- name: Merge Artifacts
|
||||||
|
uses: actions/upload-artifact/merge@v4
|
||||||
|
with:
|
||||||
|
delete-merged: true
|
||||||
|
```
|
||||||
|
|
||||||
|
After this runs, the matching artifact (`my-artifact-a`, `my-artifact-b` and `my-artifact-c`) will be merged.
|
||||||
|
|
||||||
|
### Retention and Compression Level
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
jobs:
|
||||||
|
# ... <upload job> ...
|
||||||
|
merge:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
needs: upload
|
||||||
|
steps:
|
||||||
|
- name: Merge Artifacts
|
||||||
|
uses: actions/upload-artifact/merge@v4
|
||||||
|
with:
|
||||||
|
retention-days: 1
|
||||||
|
compression-level: 9
|
||||||
|
```
|
||||||
|
|
Loading…
Reference in a new issue