feat: implement new artifact-ids input

[GrantBirki]

artifact-ids input

This pull request implements a new artifact-ids input which takes a comma separated list of artifact ids for this Action to download.

Why?

In v4, artifacts are immutable by default and each artifact gets a unique ID when uploaded. When an artifact with the same name is uploaded again (with or without overwrite: true), it gets a new artifact ID.

To take advantage of this immutability for security purposes (to avoid potential TOCTOU issues where an artifact might be replaced between upload and download), the new artifact-ids input allows you to download artifacts by their specific ID rather than by name:

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - name: Create a file
        run: echo "hello world" > my-file.txt
      - name: Upload Artifact
        id: upload
        uses: actions/upload-artifact@v4
        with:
          name: my-artifact
          path: my-file.txt
      # The upload step outputs the artifact ID
      - name: Print Artifact ID
        run: echo "Artifact ID is ${{ steps.upload.outputs.artifact-id }}"
  download:
    needs: upload
    runs-on: ubuntu-latest
    steps:
      - name: Download Artifact by ID
        uses: actions/download-artifact@v4
        with:
          # Use the artifact ID directly, not the name, to ensure you get exactly the artifact you expect
          artifact-ids: ${{ needs.upload.outputs.artifact-id }}

This approach provides stronger guarantees about which artifact version you're downloading compared to using just the artifact name.

Testing

I gave this a go in another project and it works great!

---

resolves: #349

[Copilot]

Pull Request Overview

This PR introduces a new input, artifact-ids, which allows users to download artifacts by their unique IDs rather than by name to leverage artifact immutability for enhanced security.

• Adds the artifact-ids input and associated validation logic in the download artifact code
• Updates documentation, tests, and constants to support this new input
• Modifies error messages and info logs to reflect the mutually exclusive usage of name and artifact-ids

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/download-artifact.ts	Added artifact-ids input with validation and branch handling for downloading by IDs
src/constants.ts	Updated enumeration to include artifact-ids
docs/MIGRATION.md	Documented new immutable artifacts workflow
action.yml	Introduced new input definition for artifact-ids
tests/download.test.ts	Updated test expectation messages to include artifact-ids
README.md	Enhanced documentation with examples for downloading artifacts by ID

Comments suppressed due to low confidence (1)

src/download-artifact.ts:89

• Ensure dedicated tests are added for the new artifact-ids branch, including scenarios for non-numeric input and cases where provided IDs are missing, to increase test coverage.

else if (isDownloadByIds) {

[GrantBirki]

I'm not quite sure what the release process looks like for this project so I'll just merge and leave it at that. Thanks! 🙇