@actions/download-artifact

Download Actions Artifacts from your Workflow Runs. Internally powered by the @actions/artifact package.

See also upload-artifact.

• @actions/download-artifact
  • v5 - What's new
  • v4 - What's new
    • Improvements
    • Breaking Changes
  • Note
  • Usage
    • Inputs
    • Outputs
  • Examples
    • Download Single Artifact
    • Download Artifacts by ID
    • Download All Artifacts
    • Download multiple (filtered) Artifacts to the same directory
    • Download Artifacts from other Workflow Runs or Repositories
  • Limitations
    • Permission Loss

v5 - What's new

Previously, single artifact downloads behaved differently depending on how you specified the artifact:

• By name:
  name: my-artifact
  → extracted to
  path/
  (direct)
• By ID:
  artifact-ids: 12345
  → extracted to
  path/my-artifact/
  (nested)

Now both methods are consistent:

• By name:
  name: my-artifact
  → extracted to
  path/
  (unchanged)
• By ID:
  artifact-ids: 12345
  → extracted to
  path/
  (updated - now direct)

v4 - What's new

Important

download-artifact@v4+ is not currently supported on GHES yet. If you are on GHES, you must use v3.

The release of upload-artifact@v4 and download-artifact@v4 are major changes to the backend architecture of Artifacts. They have numerous performance and behavioral improvements.

For more information, see the

documentation.

Improvements

1. Downloads are significantly faster, upwards of 90% improvement in worst case scenarios.
2. Artifacts can be downloaded from other workflow runs and repositories when supplied with a PAT.

Breaking Changes

1. On self hosted runners, additional firewall rules may be required.
2. Downloading artifacts that were created from
   action/upload-artifact@v3
   and below are not supported.

For assistance with breaking changes, see MIGRATION.md.

Note

Thank you for your interest in this GitHub repo, however, right now we are not taking contributions.

We continue to focus our resources on strategic areas that help our customers be successful while making developers' lives easier. While GitHub Actions remains a key part of this vision, we are allocating resources towards other areas of Actions and are not taking contributions to this repository at this time. The GitHub public roadmap is the best place to follow along for any updates on features we’re working on and what stage they’re in.

We are taking the following steps to better direct requests related to GitHub Actions, including:

1. We will be directing questions and support requests to our Community Discussions area

2. High Priority bugs can be reported through Community Discussions or you can report these to our support team https://support.github.com/contact/bug-report.

3. Security Issues should be handled as per our security.md.

We will still provide security updates for this project and fix major breaking changes during this time.

You are welcome to still raise bugs in this repo.

Usage

Inputs

Outputs

Examples

Download Single Artifact

Download to current working directory (

):

Download to a specific directory (also supports

expansion):

Download Artifacts by ID

The

input allows downloading artifacts using their unique ID rather than name. This is particularly useful when working with immutable artifacts from

actions/upload-artifact@v4

which assigns a unique ID to each artifact.

Download a single artifact by ID to the current working directory (

):

Download a single artifact by ID to a specific directory:

When downloading a single artifact by ID, the behavior is identical to downloading by name - the artifact contents are extracted directly to the specified path without creating a subdirectory.

Multiple artifacts can be downloaded by providing a comma-separated list of IDs:

When downloading multiple artifacts by ID, each artifact will be extracted into its own subdirectory named after the artifact (similar to downloading multiple artifacts by name).

Download All Artifacts

If the

input parameter is not provided, all artifacts will be downloaded. To differentiate between downloaded artifacts, by default a directory denoted by the artifacts name will be created for each individual artifact. This behavior can be changed with the

merge-multiple

input parameter.

Example, if there are two artifacts

and

Artifact-B

, and the directory is

etc/usr/artifacts/

, the directory structure will look like this:

etc/usr/artifacts/
    Artifact-A/
        ... contents of Artifact-A
    Artifact-B/
        ... contents of Artifact-B

Download all artifacts to the current working directory:

Download all artifacts to a specific directory:

To download them to the same directory:

Which will result in:

path/to/artifacts/
    ... contents of Artifact-A
    ... contents of Artifact-B

Download multiple (filtered) Artifacts to the same directory

In multiple arch/os scenarios, you may have Artifacts built in different jobs. To download all Artifacts to the same directory (or matching a glob pattern), you can use the

and

merge-multiple

inputs.

This results in a directory like so:

my-artifact/
  file-macos-latest.txt
  file-ubuntu-latest.txt
  file-windows-latest.txt

Download Artifacts from other Workflow Runs or Repositories

It may be useful to download Artifacts from other workflow runs, or even other repositories. By default, the permissions are scoped so they can only download Artifacts within the current workflow run. To elevate permissions for this scenario, you can specify a

along with other repository and run identifiers:

Limitations

Permission Loss

File permissions are not maintained during artifact upload. All directories will have

and all files will have

644

. For example, if you make a file executable using

chmod

and then upload that file, post-download the file is no longer guaranteed to be set as an executable.

If you must preserve permissions, you can

all of your files together before artifact upload. Post download, the

tar

file will maintain file permissions and case sensitivity.