6.8 KiB
@actions/upload-artifact/merge
Merge multiple Actions Artifacts in Workflow Runs. Internally powered by @actions/artifact package.
Usage
[!IMPORTANT] upload-artifact/merge@v4+ is not currently supported on GHES.
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 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
- uses: actions/upload-artifact/merge@v4
with:
# The name of the artifact that the artifacts will be merged into
# Optional. Default is 'merged-artifacts'
name:
# A glob pattern matching the artifacts that should be merged.
# Optional. Default is '*'
pattern:
# The desired behavior if no artifacts are found using the provided pattern.
# Available Options:
# warn: Output a warning but do not fail the action
# error: Fail the action with an error message
# ignore: Do not output any warnings or errors, the action does not fail
# Optional. Default is 'error'
if-no-files-found:
# If true, the artifacts will be merged into separate directories.
# If false, the artifacts will be merged into the root of the destination.
# Optional. Default is 'false'
separate-directories:
# If true, the artifacts that were merged will be deleted.
# If false, the artifacts will still exist.
# Optional. Default is 'false'
delete-merged:
# Duration after which artifact will expire in days. 0 means using default retention.
# Minimum 1 day.
# Maximum 90 days unless changed from the repository settings page.
# Optional. Defaults to repository settings.
retention-days:
# The level of compression for Zlib to be applied to the artifact archive.
# The value can range from 0 to 9.
# For large files that are not easily compressed, a value of 0 is recommended for significantly faster uploads.
# Optional. Default is '6'
compression-level:
Outputs
| Name | Description | Example |
|---|---|---|
artifact-id |
GitHub ID of an Artifact, can be used by the REST API | 1234 |
artifact-url |
URL to download an Artifact. Can be used in many scenarios such as linking to artifacts in issues or pull requests. Users must be logged-in in order for this URL to work. This URL is valid as long as the artifact has not expired or the artifact, run or repository have not been deleted | https://github.com/example-org/example-repo/actions/runs/1/artifacts/1234 |
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.
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:
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:
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):
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:
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 and compression-level are supported:
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