download-artifact/README.md

172 lines
5.9 KiB
Markdown
Raw Normal View History

2023-12-13 00:21:23 +00:00
# `@actions/download-artifact`
2019-07-23 19:28:49 +00:00
Download [Actions Artifacts](https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts) from your Workflow Runs. Internally powered by the [@actions/artifact](https://github.com/actions/toolkit/tree/main/packages/artifact) package.
2019-07-23 19:28:49 +00:00
2019-09-09 05:37:19 +00:00
See also [upload-artifact](https://github.com/actions/upload-artifact).
2023-12-13 00:21:23 +00:00
- [`@actions/download-artifact`](#actionsdownload-artifact)
- [v4 - What's new](#v4---whats-new)
- [Improvements](#improvements)
- [Breaking Changes](#breaking-changes)
- [Usage](#usage)
- [Inputs](#inputs)
- [Outputs](#outputs)
- [Examples](#examples)
- [Download Single Artifact](#download-single-artifact)
- [Download All Artifacts](#download-all-artifacts)
- [Download Artifacts from other Workflow Runs or Repositories](#download-artifacts-from-other-workflow-runs-or-repositories)
- [Limitations](#limitations)
- [Permission Loss](#permission-loss)
2023-12-13 00:21:23 +00:00
## v4 - What's new
2023-12-13 00:21:23 +00:00
> [!IMPORTANT]
> download-artifact@v4+ is not currently supported on GHES yet. If you are on GHES, you must use [v3](https://github.com/actions/download-artifact/releases/tag/v3).
2019-07-23 19:28:49 +00:00
2023-12-13 00:21:23 +00:00
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.
2019-07-23 19:28:49 +00:00
2023-12-13 00:21:23 +00:00
For more information, see the [`@actions/artifact`](https://github.com/actions/toolkit/tree/main/packages/artifact) documentation.
2023-12-13 00:21:23 +00:00
### 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](https://github.com/actions/toolkit/tree/main/packages/artifact#breaking-changes) may be required.
2. Downloading artifacts that were created from `action/upload-artifact@v3` and below are not supported.
## Usage
### Inputs
2019-07-23 19:28:49 +00:00
2023-12-13 00:21:23 +00:00
```yaml
- uses: actions/download-artifact@v4
2019-07-23 19:28:49 +00:00
with:
2023-12-13 00:21:23 +00:00
# Name of the artifact to download.
# Optional. If unspecified, all artifacts for the run are downloaded.
name:
# Destination path. Supports basic tilde expansion.
# Optional. Defaults is $GITHUB_WORKSPACE
path:
# The GitHub token used to authenticate with the GitHub API.
# This is required when downloading artifacts from a different repository or from a different workflow run.
# Optional. If unspecified, the action will download artifacts from the current repo and the current workflow run.
github-token:
# The repository owner and the repository name joined together by "/".
# If github-token is specified, this is the repository that artifacts will be downloaded from.
# Optional. Default is ${{ github.repository }}
repository:
# The id of the workflow run where the desired download artifact was uploaded from.
# If github-token is specified, this is the run that artifacts will be downloaded from.
# Optional. Default is ${{ github.run_id }}
2023-12-13 00:21:23 +00:00
run-id:
2019-07-23 19:28:49 +00:00
```
2023-12-13 00:21:23 +00:00
### Outputs
| Name | Description | Example |
| - | - | - |
| `download-path` | Absolute path where the artifact(s) were downloaded | `/tmp/my/download/path` |
## Examples
### Download Single Artifact
Download to current working directory (`$GITHUB_WORKSPACE`):
2019-07-23 19:28:49 +00:00
```yaml
2019-07-26 01:31:50 +00:00
steps:
2023-12-13 00:21:23 +00:00
- uses: actions/download-artifact@v4
2019-07-23 19:28:49 +00:00
with:
name: my-artifact
- name: Display structure of downloaded files
run: ls -R
```
2023-12-13 00:21:23 +00:00
Download to a specific directory (also supports `~` expansion):
2023-12-13 00:21:23 +00:00
```yaml
steps:
- uses: actions/download-artifact@v4
with:
name: my-artifact
2023-12-13 00:21:23 +00:00
path: your/destination/dir
- name: Display structure of downloaded files
run: ls -R your/destination/dir
```
2023-12-13 00:21:23 +00:00
### Download All Artifacts
If the `name` input parameter is not provided, all artifacts will be downloaded. **To differentiate between downloaded artifacts, a directory denoted by the artifacts name will be created for each individual artifact.**
2023-12-13 00:21:23 +00:00
Example, if there are two artifacts `Artifact-A` and `Artifact-B`, and the directory is `etc/usr/artifacts/`, the directory structure will look like this:
2023-12-13 00:21:23 +00:00
```
2023-12-13 00:21:23 +00:00
etc/usr/artifacts/
Artifact-A/
... contents of Artifact-A
Artifact-B/
... contents of Artifact-B
```
2023-12-13 00:21:23 +00:00
Download all artifacts to the current working directory:
```yaml
steps:
2023-12-13 00:21:23 +00:00
- uses: actions/download-artifact@v4
- name: Display structure of downloaded files
run: ls -R
```
2023-12-13 00:21:23 +00:00
Download all artifacts to a specific directory:
```yaml
steps:
2023-12-13 00:21:23 +00:00
- uses: actions/download-artifact@v4
with:
path: path/to/artifacts
- name: Display structure of downloaded files
2023-12-13 00:21:23 +00:00
run: ls -R path/to/artifacts
```
2023-12-13 00:21:23 +00:00
### Download Artifacts from other Workflow Runs or Repositories
2023-12-13 00:21:23 +00:00
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 `github-token` along with other repository and run identifiers:
```yaml
steps:
2023-12-13 00:21:23 +00:00
- uses: actions/download-artifact@v4
with:
2023-12-13 00:21:23 +00:00
name: my-other-artifact
github-token: ${{ secrets.GH_PAT }} # token with actions:read permissions on target repo
repository: actions/toolkit
run-id: 1234
```
2023-12-13 00:21:23 +00:00
## Limitations
### Permission Loss
2023-12-13 00:21:23 +00:00
File permissions are not maintained during artifact upload. All directories will have `755` 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.
2023-12-13 00:21:23 +00:00
If you must preserve permissions, you can `tar` all of your files together before artifact upload. Post download, the `tar` file will maintain file permissions and case sensitivity.
```yaml
2023-12-13 00:21:23 +00:00
- name: 'Tar files'
run: tar -cvf my_files.tar /path/to/my/directory
2019-07-23 19:28:49 +00:00
2023-12-13 00:21:23 +00:00
- name: 'Upload Artifact'
uses: actions/upload-artifact@v4
with:
name: my-artifact
path: my_files.tar
```