Merge pull request #417 from actions/yacaovsnc/update_readme

Update README for download-artifact v5 changes

README.md

@@ -5,9 +5,11 @@ Download [Actions Artifacts](https://docs.github.com/en/actions/using-workflows/
 See also [upload-artifact](https://github.com/actions/upload-artifact).
 
 - [`@actions/download-artifact`](#actionsdownload-artifact)
+  - [v5 - What's new](#v5---whats-new)
   - [v4 - What's new](#v4---whats-new)
     - [Improvements](#improvements)
     - [Breaking Changes](#breaking-changes)
+  - [Note](#note)
   - [Usage](#usage)
     - [Inputs](#inputs)
     - [Outputs](#outputs)
@@ -20,6 +22,17 @@ See also [upload-artifact](https://github.com/actions/upload-artifact).
   - [Limitations](#limitations)
     - [Permission Loss](#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
 
@@ -42,12 +55,30 @@ For more information, see the [`@actions/artifact`](https://github.com/actions/t
 
 For assistance with breaking changes, see [MIGRATION.md](docs/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](https://github.com/orgs/community/discussions/categories/actions)
+
+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](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
 
 ```yaml
-- uses: actions/download-artifact@v4
+- uses: actions/download-artifact@v5
   with:
     # Name of the artifact to download.
     # If unspecified, all artifacts for the run are downloaded.
@@ -71,6 +102,7 @@ For assistance with breaking changes, see [MIGRATION.md](docs/MIGRATION.md).
     # When multiple artifacts are matched, this changes the behavior of the destination directories.
     # If true, the downloaded artifacts will be in the same directory specified by path.
     # If false, the downloaded artifacts will be extracted into individual named directories within the specified path.
+    # Note: When downloading a single artifact (by name or ID), it will always be extracted directly to the specified path.
     # Optional. Default is 'false'
     merge-multiple:
 
@@ -104,7 +136,7 @@ Download to current working directory (`$GITHUB_WORKSPACE`):
 
 ```yaml
 steps:
-- uses: actions/download-artifact@v4
+- uses: actions/download-artifact@v5
   with:
     name: my-artifact
 - name: Display structure of downloaded files
@@ -115,7 +147,7 @@ Download to a specific directory (also supports `~` expansion):
 
 ```yaml
 steps:
-- uses: actions/download-artifact@v4
+- uses: actions/download-artifact@v5
   with:
     name: my-artifact
     path: your/destination/dir
@@ -127,20 +159,36 @@ steps:
 
 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.
 
+Download a single artifact by ID to the current working directory (`$GITHUB_WORKSPACE`):
+
 ```yaml
 steps:
-- uses: actions/download-artifact@v4
+- uses: actions/download-artifact@v5
   with:
     artifact-ids: 12345
 - name: Display structure of downloaded files
   run: ls -R
 ```
 
+Download a single artifact by ID to a specific directory:
+
+```yaml
+steps:
+- uses: actions/download-artifact@v5
+  with:
+    artifact-ids: 12345
+    path: your/destination/dir
+- name: Display structure of downloaded files
+  run: ls -R your/destination/dir
+```
+
+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:
 
 ```yaml
 steps:
-- uses: actions/download-artifact@v4
+- uses: actions/download-artifact@v5
   with:
     artifact-ids: 12345,67890
     path: path/to/artifacts
@@ -148,7 +196,7 @@ steps:
   run: ls -R path/to/artifacts
 ```
 
-This will download multiple artifacts to separate directories (similar to downloading multiple artifacts by name).
+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
 
@@ -168,7 +216,7 @@ Download all artifacts to the current working directory:
 
 ```yaml
 steps:
-- uses: actions/download-artifact@v4
+- uses: actions/download-artifact@v5
 - name: Display structure of downloaded files
   run: ls -R
 ```
@@ -177,7 +225,7 @@ Download all artifacts to a specific directory:
 
 ```yaml
 steps:
-- uses: actions/download-artifact@v4
+- uses: actions/download-artifact@v5
   with:
     path: path/to/artifacts
 - name: Display structure of downloaded files
@@ -188,7 +236,7 @@ To download them to the _same_ directory:
 
 ```yaml
 steps:
-- uses: actions/download-artifact@v4
+- uses: actions/download-artifact@v5
   with:
     path: path/to/artifacts
     merge-multiple: true
@@ -228,7 +276,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Download All Artifacts
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v5
       with:
         path: my-artifact
         pattern: my-artifact-*
@@ -251,7 +299,7 @@ It may be useful to download Artifacts from other workflow runs, or even other r
 
 ```yaml
 steps:
-- uses: actions/download-artifact@v4
+- uses: actions/download-artifact@v5
   with:
     name: my-other-artifact
     github-token: ${{ secrets.GH_PAT }} # token with actions:read permissions on target repo

__tests__/download.test.ts

@@ -1,4 +1,5 @@
 import * as core from '@actions/core'
+import * as path from 'path'
 import artifact, {ArtifactNotFoundError} from '@actions/artifact'
 import {run} from '../src/download-artifact'
 import {Inputs} from '../src/constants'
@@ -371,4 +372,38 @@ describe('download', () => {
       "Inputs 'name' and 'artifact-ids' cannot be used together. Please specify only one."
     )
   })
+
+  test('downloads single artifact by ID to same path as by name', async () => {
+    const mockArtifact = {
+      id: 456,
+      name: 'test-artifact',
+      size: 1024,
+      digest: 'def456'
+    }
+
+    const testPath = '/test/path'
+    mockInputs({
+      [Inputs.Name]: '',
+      [Inputs.Pattern]: '',
+      [Inputs.ArtifactIds]: '456',
+      [Inputs.Path]: testPath
+    })
+
+    jest.spyOn(artifact, 'listArtifacts').mockImplementation(() =>
+      Promise.resolve({
+        artifacts: [mockArtifact]
+      })
+    )
+
+    await run()
+
+    // Verify it downloads directly to the specified path (not nested in artifact name subdirectory)
+    expect(artifact.downloadArtifact).toHaveBeenCalledWith(
+      456,
+      expect.objectContaining({
+        path: path.resolve(testPath), // Should be the resolved path directly, not nested
+        expectedHash: mockArtifact.digest
+      })
+    )
+  })
 })

dist/index.js

@@ -118883,7 +118883,9 @@ function run() {
         }
         const downloadPromises = artifacts.map(artifact => ({
             name: artifact.name,
-            promise: artifact_1.default.downloadArtifact(artifact.id, Object.assign(Object.assign({}, options), { path: isSingleArtifactDownload || inputs.mergeMultiple
+            promise: artifact_1.default.downloadArtifact(artifact.id, Object.assign(Object.assign({}, options), { path: isSingleArtifactDownload ||
+                    inputs.mergeMultiple ||
+                    artifacts.length === 1
                     ? resolvedPath
                     : path.join(resolvedPath, artifact.name), expectedHash: artifact.digest }))
         }));

src/download-artifact.ts

@@ -174,7 +174,9 @@ export async function run(): Promise<void> {
     promise: artifactClient.downloadArtifact(artifact.id, {
       ...options,
       path:
-        isSingleArtifactDownload || inputs.mergeMultiple
+        isSingleArtifactDownload ||
+        inputs.mergeMultiple ||
+        artifacts.length === 1
           ? resolvedPath
           : path.join(resolvedPath, artifact.name),
       expectedHash: artifact.digest