Skip to content

Commit 484a0b5

Browse files
authored
Update the readme (#473)
* Update the readme * Update upload artifact versions * Add back the GHES support note * Update the skip-decompress description * Be more specific with the direct download example * Add GHES support section to TOC
1 parent 3e5f45b commit 484a0b5

1 file changed

Lines changed: 71 additions & 102 deletions

File tree

‎README.md‎

Lines changed: 71 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -4,87 +4,23 @@ Download [Actions Artifacts](https://docs.github.com/en/actions/using-workflows/
44

55
See also [upload-artifact](https://github.com/actions/upload-artifact).
66

7-
- [`@actions/download-artifact`](#actionsdownload-artifact)
8-
- [v7 - What's new](#v7---whats-new)
9-
- [v5 - What's new](#v5---whats-new)
10-
- [v4 - What's new](#v4---whats-new)
11-
- [Improvements](#improvements)
12-
- [Breaking Changes](#breaking-changes)
13-
- [Note](#note)
14-
- [Usage](#usage)
15-
- [Inputs](#inputs)
16-
- [Outputs](#outputs)
17-
- [Examples](#examples)
18-
- [Download Single Artifact](#download-single-artifact)
19-
- [Download Artifacts by ID](#download-artifacts-by-id)
20-
- [Download All Artifacts](#download-all-artifacts)
21-
- [Download multiple (filtered) Artifacts to the same directory](#download-multiple-filtered-artifacts-to-the-same-directory)
22-
- [Download Artifacts from other Workflow Runs or Repositories](#download-artifacts-from-other-workflow-runs-or-repositories)
23-
- [Limitations](#limitations)
24-
- [Permission Loss](#permission-loss)
25-
26-
## v8 - What's new
27-
28-
> [!IMPORTANT]
29-
> actions/download-artifact@v8 has been migrated to an ESM module. This should be transparent to the caller but forks might need to make significant changes.
30-
31-
> [!IMPORTANT]
32-
> Hash mismatches will now error by default. Users can override this behavior with a setting change (see below).
33-
34-
- Downloads will check the content-type returned to determine if a file can be decompressed and skip the decompression stage if so. This removes previous failures where we were trying to decompress a non-zip file. Since this is making a big change to the default behavior, we're making it opt-in via a version bump.
35-
- Users can also download a zip file without decompressing it with the new `skip-decompress` flag.
36-
37-
- Introduces a new parameter `digest-mismatch` that allows callers to specify what to do when the downloaded hash doesn't match the expected hash (`ignore`, `info`, `warn`, `error`). To ensure security by default, the default value is `error`.
38-
39-
- Chore: we've bumped versions on a lot of our dev packages to get them up to date with the latest bugfixes/security patches.
40-
41-
### v8.0.1
42-
43-
- Support for CJK (Chinese/Japanese/Korean) characters in the file name.
44-
45-
## v7 - What's new
46-
47-
> [!IMPORTANT]
48-
> actions/download-artifact@v7 now runs on Node.js 24 (`runs.using: node24`) and requires a minimum Actions Runner version of 2.327.1. If you are using self-hosted runners, ensure they are updated before upgrading.
49-
50-
### Node.js 24
51-
52-
This release updates the runtime to Node.js 24. v6 had preliminary support for Node 24, however this action was by default still running on Node.js 20. Now this action by default will run on Node.js 24.
53-
54-
## v5 - What's new
55-
56-
Previously, **single artifact downloads** behaved differently depending on how you specified the artifact:
57-
58-
- **By name**: `name: my-artifact` → extracted to `path/` (direct)
59-
- **By ID**: `artifact-ids: 12345` → extracted to `path/my-artifact/` (nested)
60-
61-
Now both methods are consistent:
62-
63-
- **By name**: `name: my-artifact` → extracted to `path/` (unchanged)
64-
- **By ID**: `artifact-ids: 12345` → extracted to `path/` (updated - now direct)
65-
66-
Note: This change also applies to patterns that only match a single artifact.
67-
68-
## v4 - What's new
69-
70-
> [!IMPORTANT]
71-
> download-artifact@v4+ is not currently supported on GitHub Enterprise Server (GHES) yet. If you are on GHES, you must use [v3](https://github.com/actions/download-artifact/releases/tag/v3) (Node 16) or [v3-node20](https://github.com/actions/download-artifact/releases/tag/v3-node20) (Node 20).
72-
73-
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.
74-
75-
For more information, see the [`@actions/artifact`](https://github.com/actions/toolkit/tree/main/packages/artifact) documentation.
76-
77-
### Improvements
78-
79-
1. Downloads are significantly faster, upwards of 90% improvement in worst case scenarios.
80-
2. Artifacts can be downloaded from other workflow runs and repositories when supplied with a PAT.
81-
82-
### Breaking Changes
83-
84-
1. On self hosted runners, additional [firewall rules](https://github.com/actions/toolkit/tree/main/packages/artifact#breaking-changes) may be required.
85-
2. Downloading artifacts that were created from `action/upload-artifact@v3` and below are not supported.
86-
87-
For assistance with breaking changes, see [MIGRATION.md](docs/MIGRATION.md).
7+
- [What's new](#whats-new)
8+
- [Note](#note)
9+
- [GHES Support](#ghes-support)
10+
- [Usage](#usage)
11+
- [Inputs](#inputs)
12+
- [Outputs](#outputs)
13+
- [Examples](#examples)
14+
- [Download Single Artifact](#download-single-artifact)
15+
- [Download Artifacts by ID](#download-artifacts-by-id)
16+
- [Download All Artifacts](#download-all-artifacts)
17+
- [Download multiple (filtered) Artifacts to the same directory](#download-multiple-filtered-artifacts-to-the-same-directory)
18+
- [Download Artifacts from other Workflow Runs or Repositories](#download-artifacts-from-other-workflow-runs-or-repositories)
19+
- [Maintaining File Permissions](#maintaining-file-permissions)
20+
21+
## What's new
22+
23+
Check out the [releases page](https://github.com/actions/download-artifact/releases) for details on what's new.
8824

8925
## Note
9026

@@ -104,12 +40,16 @@ We will still provide security updates for this project and fix major breaking c
10440

10541
You are welcome to still raise bugs in this repo.
10642

43+
## GHES Support
44+
45+
`download-artifact@v4+` is not currently supported on GitHub Enterprise Server (GHES) yet. If you are on GHES, you must use [v3](https://github.com/actions/download-artifact/releases/tag/v3) (Node 16) or [v3-node20](https://github.com/actions/download-artifact/releases/tag/v3-node20) (Node 20).
46+
10747
## Usage
10848

10949
### Inputs
11050

11151
```yaml
112-
- uses: actions/download-artifact@v5
52+
- uses: actions/download-artifact@v8
11353
with:
11454
# Name of the artifact to download.
11555
# If unspecified, all artifacts for the run are downloaded.
@@ -151,6 +91,17 @@ You are welcome to still raise bugs in this repo.
15191
# If github-token is specified, this is the run that artifacts will be downloaded from.
15292
# Optional. Default is ${{ github.run_id }}
15393
run-id:
94+
95+
# Whether to skip decompressing a zip file (if detected).
96+
# If true, the downloaded artifact will not be automatically extracted/decompressed.
97+
# This is useful when you want to handle the artifact as-is without extraction.
98+
# Optional. Default is `false`
99+
skip-decompress:
100+
101+
# What to do if the action detects a mismatch between the downloaded hash and the expected hash from the server.
102+
# Can be one of: `ignore`, `info`, `warn`, `error`
103+
# Optional. Default is `error`
104+
digest-mismatch:
154105
```
155106
156107
### Outputs
@@ -167,7 +118,7 @@ Download to current working directory (`$GITHUB_WORKSPACE`):
167118

168119
```yaml
169120
steps:
170-
- uses: actions/download-artifact@v5
121+
- uses: actions/download-artifact@v8
171122
with:
172123
name: my-artifact
173124
- name: Display structure of downloaded files
@@ -178,23 +129,32 @@ Download to a specific directory (also supports `~` expansion):
178129

179130
```yaml
180131
steps:
181-
- uses: actions/download-artifact@v5
132+
- uses: actions/download-artifact@v8
182133
with:
183134
name: my-artifact
184135
path: your/destination/dir
185136
- name: Display structure of downloaded files
186137
run: ls -R your/destination/dir
187138
```
188139

140+
Directly download a non-zipped file (only supports files uploaded with `actions/upload-artifact@v7` and `archive: false` set):
141+
142+
```yaml
143+
steps:
144+
- uses: actions/download-artifact@v8
145+
with:
146+
name: my-artifact.json # corresponds to the uploaded file name
147+
```
148+
189149
### Download Artifacts by ID
190150

191-
The `artifact-ids` 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.
151+
The `artifact-ids` 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.
192152

193153
Download a single artifact by ID to the current working directory (`$GITHUB_WORKSPACE`):
194154

195155
```yaml
196156
steps:
197-
- uses: actions/download-artifact@v5
157+
- uses: actions/download-artifact@v8
198158
with:
199159
artifact-ids: 12345
200160
- name: Display structure of downloaded files
@@ -205,7 +165,7 @@ Download a single artifact by ID to a specific directory:
205165

206166
```yaml
207167
steps:
208-
- uses: actions/download-artifact@v5
168+
- uses: actions/download-artifact@v8
209169
with:
210170
artifact-ids: 12345
211171
path: your/destination/dir
@@ -219,7 +179,7 @@ Multiple artifacts can be downloaded by providing a comma-separated list of IDs:
219179

220180
```yaml
221181
steps:
222-
- uses: actions/download-artifact@v5
182+
- uses: actions/download-artifact@v8
223183
with:
224184
artifact-ids: 12345,67890
225185
path: path/to/artifacts
@@ -247,7 +207,7 @@ Download all artifacts to the current working directory:
247207

248208
```yaml
249209
steps:
250-
- uses: actions/download-artifact@v5
210+
- uses: actions/download-artifact@v8
251211
- name: Display structure of downloaded files
252212
run: ls -R
253213
```
@@ -256,7 +216,7 @@ Download all artifacts to a specific directory:
256216

257217
```yaml
258218
steps:
259-
- uses: actions/download-artifact@v5
219+
- uses: actions/download-artifact@v8
260220
with:
261221
path: path/to/artifacts
262222
- name: Display structure of downloaded files
@@ -267,7 +227,7 @@ To download them to the _same_ directory:
267227

268228
```yaml
269229
steps:
270-
- uses: actions/download-artifact@v5
230+
- uses: actions/download-artifact@v8
271231
with:
272232
path: path/to/artifacts
273233
merge-multiple: true
@@ -298,7 +258,7 @@ jobs:
298258
- name: Create a File
299259
run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
300260
- name: Upload Artifact
301-
uses: actions/upload-artifact@v4
261+
uses: actions/upload-artifact@v7
302262
with:
303263
name: my-artifact-${{ matrix.runs-on }}
304264
path: file-${{ matrix.runs-on }}.txt
@@ -307,7 +267,7 @@ jobs:
307267
runs-on: ubuntu-latest
308268
steps:
309269
- name: Download All Artifacts
310-
uses: actions/download-artifact@v5
270+
uses: actions/download-artifact@v8
311271
with:
312272
path: my-artifact
313273
pattern: my-artifact-*
@@ -330,29 +290,38 @@ It may be useful to download Artifacts from other workflow runs, or even other r
330290

331291
```yaml
332292
steps:
333-
- uses: actions/download-artifact@v5
293+
- uses: actions/download-artifact@v8
334294
with:
335295
name: my-other-artifact
336296
github-token: ${{ secrets.GH_PAT }} # token with actions:read permissions on target repo
337297
repository: actions/toolkit
338298
run-id: 1234
339299
```
340300

341-
## Limitations
342-
343-
### Permission Loss
301+
### Maintaining File Permissions
344302

345-
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.
303+
Zipping files will remove file permissions 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 as a zip file, post-download the file is no longer guaranteed to be set as an executable.
346304

347-
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.
305+
If you must preserve permissions, you can `tar` all of your files together before artifact upload and upload it as a single file (using V7+ of `actions/upload-artifact`). Then download the file directly and unpack it manually:
348306

349307
```yaml
308+
350309
- name: 'Tar files'
351310
run: tar -cvf my_files.tar /path/to/my/directory
352311
353312
- name: 'Upload Artifact'
354-
uses: actions/upload-artifact@v4
313+
uses: actions/upload-artifact@v7
355314
with:
356-
name: my-artifact
357315
path: my_files.tar
358-
```
316+
archive: false
317+
318+
----
319+
320+
# Later, download the file by name
321+
322+
- name: 'Download Artifact'
323+
uses: actions/download-artifact@v8
324+
with:
325+
name: my_files.tar
326+
327+
```

0 commit comments

Comments
 (0)