actions/download-artifact
1
0
Fork 0
mirror of https://github.com/actions/download-artifact.git synced 2024-12-22 14:22:42 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #245 from actions/robherley/v4-documentation

Browse source 
Update documentation for v4
This commit is contained in:
Rob Herley 2023-12-13 13:00:28 -05:00 committed by GitHub
commit b5ff8444b1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 32434 additions and 11601 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
.github/workflows/check-dist.yml vendored
View file

@ -22,12 +22,12 @@ jobs:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- uses: actions/checkout@v3 - uses: actions/checkout@v4
- name: Setup Node 16 - name: Setup Node 20
uses: actions/setup-node@v3 uses: actions/setup-node@v4
with: with:
node-version: 16.x node-version: 20.x
cache: 'npm' cache: 'npm'
- name: Install dependencies - name: Install dependencies
@ -46,7 +46,7 @@ jobs:
id: diff id: diff
# If index.js was different than expected, upload the expected version as an artifact # If index.js was different than expected, upload the expected version as an artifact
- uses: actions/upload-artifact@v3 - uses: actions/upload-artifact@v4-beta
if: ${{ failure() && steps.diff.conclusion == 'failure' }} if: ${{ failure() && steps.diff.conclusion == 'failure' }}
with: with:
name: dist name: dist

2
.github/workflows/licensed.yml vendored
View file

@ -13,7 +13,7 @@ jobs:
runs-on: ubuntu-latest runs-on: ubuntu-latest
name: Check licenses name: Check licenses
steps: steps:
- uses: actions/checkout@v3 - uses: actions/checkout@v4
- run: npm ci - run: npm ci
- name: Install licensed - name: Install licensed
run: | run: |

34
.github/workflows/test.yml vendored
View file

@ -8,7 +8,6 @@ on:
- '**.md' - '**.md'
jobs: jobs:
build: build:
name: Build name: Build
@ -21,13 +20,12 @@ jobs:
steps: steps:
- name: Checkout - name: Checkout
uses: actions/checkout@v3 uses: actions/checkout@v4
# using node 16 since that is what the latest version of the runner ships with - name: Setup Node 20
- name: Setup Node 16 uses: actions/setup-node@v4
uses: actions/setup-node@v3
with: with:
node-version: 16.x node-version: 20.x
cache: 'npm' cache: 'npm'
- name: npm install - name: npm install
@ -40,41 +38,39 @@ jobs:
run: npm run lint run: npm run lint
- name: Format - name: Format
run: npm run format-check run: npm run format-check
# Test end-to-end by uploading two artifacts and then downloading them
# Once upload-artifact v2 is out of preview, switch over
- name: Create artifacts - name: Create artifacts
run: | run: |
mkdir -p path/to/artifact-A mkdir -p path/to/artifact-A
mkdir -p path/to/artifact-B mkdir -p path/to/artifact-B
echo "Lorem ipsum dolor sit amet" > path/to/artifact-A/file-A.txt echo "Lorem ipsum dolor sit amet" > path/to/artifact-A/file-A.txt
echo "Hello world from file B" > path/to/artifact-B/file-B.txt echo "Hello world from file B" > path/to/artifact-B/file-B.txt
- name: Upload artifact A - name: Upload artifact A
uses: actions/upload-artifact@v1 uses: actions/upload-artifact@v4-beta
with: with:
name: 'Artifact-A' name: Artifact-A-${{ matrix.runs-on }}
path: path/to/artifact-A path: path/to/artifact-A
- name: Upload artifact B - name: Upload artifact B
uses: actions/upload-artifact@v1 uses: actions/upload-artifact@v4-beta
with: with:
name: 'Artifact-B' name: Artifact-B-${{ matrix.runs-on }}
path: path/to/artifact-B path: path/to/artifact-B
# Test downloading a single artifact # Test downloading a single artifact
- name: Download artifact A - name: Download artifact A
uses: ./ uses: ./
with: with:
name: 'Artifact-A' name: Artifact-A-${{ matrix.runs-on }}
path: some/new/path path: some/new/path
# Test downloading an artifact using tilde expansion # Test downloading an artifact using tilde expansion
- name: Download artifact A - name: Download artifact A
uses: ./ uses: ./
with: with:
name: 'Artifact-A' name: Artifact-A-${{ matrix.runs-on }}
path: ~/some/path/with/a/tilde path: ~/some/path/with/a/tilde
- name: Verify successful download - name: Verify successful download
@ -99,8 +95,8 @@ jobs:
- name: Verify successful download - name: Verify successful download
run: | run: |
$fileA = "some/other/path/Artifact-A/file-A.txt" $fileA = "some/other/path/Artifact-A-${{ matrix.runs-on }}/file-A.txt"
$fileB = "some/other/path/Artifact-B/file-B.txt" $fileB = "some/other/path/Artifact-B-${{ matrix.runs-on }}/file-B.txt"
if(!(Test-Path -path $fileA) -or !(Test-Path -path $fileB)) if(!(Test-Path -path $fileA) -or !(Test-Path -path $fileB))
{ {
Write-Error "Expected files do not exist" Write-Error "Expected files do not exist"
@ -110,5 +106,3 @@ jobs:
Write-Error "File contents of downloaded artifacts are incorrect" Write-Error "File contents of downloaded artifacts are incorrect"
} }
shell: pwsh shell: pwsh

232
README.md
View file

@ -1,169 +1,171 @@
# Download-Artifact v3 # `@actions/download-artifact`
This downloads artifacts from your build 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.
See also [upload-artifact](https://github.com/actions/upload-artifact). See also [upload-artifact](https://github.com/actions/upload-artifact).
# What's new - [`@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)
- Download all artifacts at once
- Output parameter for the download path
- Port entire action to typescript from a runner plugin so it is easier to collaborate and accept contributions
Refer [here](https://github.com/actions/download-artifact/tree/v2) for the previous version ## v4 - What's new
# Usage > [!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).
See [action.yml](action.yml) 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.
# Download a Single Artifact For more information, see the [`@actions/artifact`](https://github.com/actions/toolkit/tree/main/packages/artifact) 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](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
```yaml
- uses: actions/download-artifact@v4
with:
# 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.repository }}
run-id:
```
### 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`):
Basic (download to the current working directory):
```yaml ```yaml
steps: steps:
- uses: actions/checkout@v3 - uses: actions/download-artifact@v4
- uses: actions/download-artifact@v3
with: with:
name: my-artifact name: my-artifact
- name: Display structure of downloaded files - name: Display structure of downloaded files
run: ls -R run: ls -R
``` ```
Download to a specific directory: Download to a specific directory (also supports `~` expansion):
```yaml ```yaml
steps: steps:
- uses: actions/checkout@v3 - uses: actions/download-artifact@v4
- uses: actions/download-artifact@v3
with: with:
name: my-artifact name: my-artifact
path: path/to/artifact path: your/destination/dir
- name: Display structure of downloaded files - name: Display structure of downloaded files
run: ls -R run: ls -R your/destination/dir
working-directory: path/to/artifact
```
Basic tilde expansion is supported for the `path` input:
```yaml
- uses: actions/download-artifact@v3
with:
name: my-artifact
path: ~/download/path
```
## Compatibility between `v1` and `v2`/`v3`
When using `download-artifact@v1`, a directory denoted by the name of the artifact would be created if the `path` input was not provided. All of the contents would be downloaded to this directory.
```
current/working/directory/
my-artifact/
... contents of my-artifact
```
With `v2` and `v3`, when an artifact is specified by the `name` input, there is no longer an extra directory that is created if the `path` input is not provided. All the contents are downloaded to the current working directory.
```
current/working/directory/
... contents of my-artifact
```
To maintain the same behavior for `v2` and `v3`, you can set the `path` to the name of the artifact so an extra directory gets created.
```
- uses: actions/download-artifact@v2
with:
name: my-artifact
path: my-artifact
``` ```
# Download All Artifacts ### 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.** 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.**
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: 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:
``` ```
etc/usr/artifacts/ etc/usr/artifacts/
Artifact-A/ Artifact-A/
... contents of Artifact-A ... contents of Artifact-A
Artifact-B/ Artifact-B/
... contents of Artifact-B ... contents of Artifact-B
``` ```
Download all artifacts to a specific directory Download all artifacts to the current working directory:
```yaml ```yaml
steps: steps:
- uses: actions/checkout@v3 - uses: actions/download-artifact@v4
- uses: actions/download-artifact@v3
with:
path: path/to/artifacts
- name: Display structure of downloaded files
run: ls -R
working-directory: path/to/artifacts
```
Download all artifacts to the current working directory
```yaml
steps:
- uses: actions/checkout@v3
- uses: actions/download-artifact@v3
- name: Display structure of downloaded files - name: Display structure of downloaded files
run: ls -R run: ls -R
``` ```
# Download path output Download all artifacts to a specific directory:
The `download-path` step output contains information regarding where the artifact was downloaded to. This output can be used for a variety of purposes such as logging or as input to other actions. Be aware of the extra directory that is created if downloading all artifacts (no name specified).
```yaml ```yaml
steps: steps:
- uses: actions/checkout@v3 - uses: actions/download-artifact@v4
- uses: actions/download-artifact@v3
id: download
with: with:
name: 'my-artifact'
path: path/to/artifacts path: path/to/artifacts
- name: Display structure of downloaded files
- name: 'Echo download path' run: ls -R path/to/artifacts
run: echo ${{steps.download.outputs.download-path}}
``` ```
> Note: The `id` defined in the `download/artifact` step must match the `id` defined in the `echo` step (i.e `steps.[ID].outputs.download-path`) ### Download Artifacts from other Workflow Runs or Repositories
# Limitations 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:
- uses: actions/download-artifact@v4
with:
name: my-other-artifact
github-token: ${{ secrets.GH_PAT }} # token with actions:read permissions on target repo
repository: actions/toolkit
run-id: 1234
```
## Limitations
### Permission Loss ### Permission Loss
:exclamation: File permissions are not maintained during artifact upload :exclamation: 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. 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.
### Case Insensitive Uploads 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.
:exclamation: File uploads are case insensitive :exclamation: If you upload `A.txt` and `a.txt` with the same root path, only a single file will be saved and available during download.
### Maintaining file permissions and case sensitive files
If file permissions and case sensitivity are required, you can `tar` all of your files together before artifact upload. Post download, the `tar` file will maintain file permissions and case sensitivity.
```yaml ```yaml
- name: 'Tar files' - name: 'Tar files'
run: tar -cvf my_files.tar /path/to/my/directory run: tar -cvf my_files.tar /path/to/my/directory
- name: 'Upload Artifact' - name: 'Upload Artifact'
uses: actions/upload-artifact@v2 uses: actions/upload-artifact@v4
with: with:
name: my-artifact name: my-artifact
path: my_files.tar path: my_files.tar
``` ```
# @actions/artifact package
Internally the [@actions/artifact](https://github.com/actions/toolkit/tree/main/packages/artifact) NPM package is used to interact with artifacts. You can find additional documentation there along with all the source code related to artifact download.
# License
The scripts and documentation in this project are released under the [MIT License](LICENSE)

4
action.yml
View file

@ -3,10 +3,10 @@ description: 'Download a build artifact that was previously uploaded in the work
author: 'GitHub' author: 'GitHub'
inputs: inputs:
name: name:
description: 'Artifact name' description: 'Name of the artifact to download. If unspecified, all artifacts for the run are downloaded'
required: false required: false
path: path:
description: 'Destination path' description: 'Destination path. Supports basic tilde expansion. Defaults to $GITHUB_WORKSPACE'
required: false required: false
github-token: github-token:
description: 'The GitHub token used to authenticate with the GitHub API. description: 'The GitHub token used to authenticate with the GitHub API.

41765
dist/index.js vendored
View file

File diff suppressed because one or more lines are too long

1984
package-lock.json generated
View file

File diff suppressed because it is too large Load diff

4
package.json
View file

@ -1,7 +1,7 @@
{ {
"name": "download-artifact", "name": "download-artifact",
"version": "3.0.0", "version": "4.0.0",
"description": "Download a build artifact that was previously uploaded in the workflow by the upload-artifact action", "description": "Download an Actions Artifact from a workflow run",
"main": "dist/index.js", "main": "dist/index.js",
"scripts": { "scripts": {
"build": "tsc", "build": "tsc",