fix: inconsistent path behavior for single artifact downloads by ID

[GrantBirki]

Inconsistent path behavior for single artifact downloads by ID

When downloading a single artifact, there is an inconsistency in the path behavior depending on how the artifact was specified:

• By name: artifact-ids: my-artifact → extracts directly to specified path (e.g., dist/)
• By ID: artifact-ids: 12345 → creates nested directory (e.g., dist/my-artifact/)

This inconsistency was confusing and may have forced users to work around it by setting merge-multiple: true even for single artifact downloads.

Solution

Modified the path determination logic to treat single artifact downloads consistently, regardless of whether they're specified by name or artifact ID.

Key change: Added artifacts.length === 1 condition to the path logic, so single artifact downloads always extract directly to the specified path.

---

related: urllib3/urllib3#3650 (another PR I opened as a workaround since this inconsistency still exists)

[Copilot]

Pull Request Overview

This PR fixes an inconsistency in path behavior for single artifact downloads, where artifacts downloaded by ID were creating nested directories while artifacts downloaded by name extracted directly to the specified path.

• Added condition artifacts.length === 1 to the path determination logic for consistent single artifact download behavior
• Updated test coverage to verify single artifact downloads by ID extract to the same path as downloads by name
• Enhanced documentation to clarify the consistent behavior for single artifact downloads

Reviewed Changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated no comments.

File	Description
src/download-artifact.ts	Modified path logic to treat single artifact downloads consistently regardless of specification method
tests/download.test.ts	Added test case verifying single artifact by ID downloads to same path as by name
README.md	Updated documentation to clarify consistent single artifact download behavior and added examples

[GrantBirki]

Here is the original PR where I added support for downloading artifacts by id but missed this behavior leading to an inconsistency -> #401

[robherley]

This makes sense to me 👍 cc @yacaovsnc @Link-

[yacaovsnc]

The change LGTM so I approved. This is a breaking change so we may need to be a bit more careful in releasing this.

[GrantBirki]

@yacaovsnc v5 release notes will look something like this since this will be a breaking change for folks that have already adopted the new_ish_ artifact-ids input option:

v5.0.0

🚨 Breaking Change

This release fixes an inconsistency in path behavior for single artifact downloads by ID. If you're downloading single artifacts by ID, the output path may change.

What Changed

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/ (fixed - now direct)

Migration Guide

✅ No Action Needed If:

• You download artifacts by name
• You download multiple artifacts by ID
• You already use merge-multiple: true as a workaround

⚠️ Action Required If:

You download single artifacts by ID and your workflows expect the nested directory structure.

Before v5 (nested structure):

- uses: actions/download-artifact@v4
  with:
    artifact-ids: 12345
    path: dist
# Files were in: dist/my-artifact/

Where my-artifact is the name of the artifact you previously uploaded

To maintain old behavior (if needed):

- uses: actions/download-artifact@v5
  with:
    artifact-ids: 12345
    path: dist/my-artifact  # Explicitly specify the nested path

[agners]

👋 it seems there is another, potentially unintended change:

Previously, artifact downloads without using name or id was consistent, e.g.:

• [no name/all artifacts if 1]: → extracted to path/my-artifact/ (nested)
• [no name/all artifacts if multiple]: → extracted to path/my-artifact/, path/my-artifact2/ (nested)

Now behavior depends on how many artifacts are there, e.g.:

• [no name/all artifacts if 1]: → extracted to path/ (changed - now direct)
• [no name/all artifacts if multiple]: → extracted to path/my-artifact/, path/my-artifact2/ (unchanged - nested)

IMHO, this behavior is not ideal as we can't use generic handling for matrices of size 1 and bigger than 1.

[Zharktas]

Our builds broke due to this, as we build containers in a matrix and only some of them are built in pipeline. Our jobs with download-artifact action download all artifacts without name or ID and the job assumes that the artifact will be in a nested path.

Now the job succeedes if there are multiple artifacts as they are in a nested path, but it fails if there is only 1 artifact as it is not nested anymore.

[audunsolemdal]

Our builds broke due to this, as we build containers in a matrix and only some of them are built in pipeline. Our jobs with download-artifact action download all artifacts without name or ID and the job assumes that the artifact will be in a nested path.

Now the job succeedes if there are multiple artifacts as they are in a nested path, but it fails if there is only 1 artifact as it is not nested anymore.

Had the exact same thing happen, found a workaround if you are interested in using v5.

jobs:
  plan:
    needs: detect
    if: ${{ needs.detect.outputs.directories != '{}' }}
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJson(needs.detect.outputs.directories) }}
      fail-fast: false
    outputs:
      job-total: ${{ strategy.job-total }}
      name: "${{ matrix.directory || 'main' }}"
    name: "Module: ${{ matrix.directory }}"
    steps:
    ...
      - name: Upload result artifacts
        uses: actions/upload-artifact@v4
        with:
          name: "${{ matrix.directory || 'main' }}"
          path: output
          retention-days: 5

  comment:
    needs: [detect, plan]
    runs-on: ubuntu-latest
    name: "Comment on PR"
    steps:
      - name: Download artifact(s)
        uses: actions/download-artifact@v5
        with:
          path: ${{needs.plan.outputs.job-total == 1 && format('outputs/{0}', needs.plan.outputs.name) || 'outputs' }} 
   ...

the essence is outputting ${{ strategy.job-total }} from the matrix job and customizing the path depending if the matrix count is 1 or more than 1.

Repo with more details if interested: miljodir/workflow-templates#19

[avdland]

The behaviour is inconsistent if you use the pattern input.
If there is only one artifact, then it will download and unpack straight into the workspace, but if there is more than one, then the artifact will be unpacked into a directory (named after the artifact).

Before (which broke our workflow):

- name: Download ${{ matrix.type }} artifacts
  uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
  with:
    pattern: build-${{ matrix.type }}-*

After (which is similar to v4 behaviour):

- name: Download ${{ matrix.type }} artifacts
  run: |
    MATCHED=$(gh api repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/artifacts \
      --jq '.artifacts[] | select(.name | test("^build-${{ matrix.type }}-")) | .name')
    echo "$MATCHED" | while read -r name; do
      echo "Downloading $name..."
      gh run download ${{ github.run_id }} -n "$name" -D "$name"
    done
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

[jeroen]

This has created some inconsistent behavior when downloading all artifacts: #455