7.4 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:
# 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:
Uploading the .git directory
By default, files in a .git directory are ignored in the merged artifact.
This is intended to prevent accidentally uploading Git credentials into an artifact that could then
be extracted.
If files in the .git directory are needed, ensure that actions/checkout is being used with
persist-credentials: false.
jobs:
upload:
runs-on: ubuntu-latest
strategy:
matrix:
foo: [a, b, c]
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false # Ensure credentials are not saved in `.git/config`
- name: Upload
uses: actions/upload-artifact@v4
with:
name: my-artifact-${{ matrix.foo }}
path: .
include-git-directory: true
merge:
runs-on: ubuntu-latest
steps:
- uses: actions/upload-artifact/merge@v4
with:
include-git-directory: true
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