### Download All Artifacts in a Setup Job

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/quick-reference.md

Download all artifacts into a specified path within a setup job. This is useful for preparing artifacts before other jobs run.

```yaml
jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v8
        with:
          pattern: '*'
          path: ./all-artifacts
          merge-multiple: true
```

--------------------------------

### Install Dependencies

Source: https://github.com/actions/download-artifact/blob/main/CONTRIBUTING.md

Install project dependencies using npm.

```bash
npm install
```

--------------------------------

### Download Artifacts in Workflow

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/types.md

Example of downloading artifacts in a GitHub Actions workflow and accessing the output path.

```yaml
- name: Download artifacts
  id: download
  uses: actions/download-artifact@v8
  with:
    path: ./artifacts

- name: Display download location
  run: |
    echo "Downloaded to: ${{ steps.download.outputs.download-path }}"
    ls -R "${{ steps.download.outputs.download-path }}"
```

--------------------------------

### Batch Process Downloads with Chunk

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/api-reference-chunk.md

Illustrates using the chunk function to batch download promises. This example processes downloads in batches of 5 to manage concurrency.

```typescript
import {chunk} from './download-artifact'

const downloadPromises = artifacts.map(artifact => ({
  name: artifact.name,
  promise: downloadArtifact(artifact.id)
}))

const batches = chunk(downloadPromises, 5)

for (const batch of batches) {
  // Process 5 downloads in parallel, wait for all to complete
  const results = await Promise.all(batch.map(item => item.promise))
  // Then move to next batch
}
```

--------------------------------

### Developer Navigation Pattern

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/INDEX.md

This pattern illustrates the documentation path for developers, starting with architecture and implementation details, then moving to function flow and utility functions.

```markdown
README.md (architecture)
    ↓
implementation-details.md (how it works)
    ↓
api-reference-run.md (function flow)
    ↓
api-reference-chunk.md (utilities)
```

--------------------------------

### Integrator Navigation Pattern

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/INDEX.md

This pattern guides integrators on navigating the documentation, beginning with an overview and progressing to function specifics, input options, and error handling.

```markdown
README.md (overview)
    ↓
api-reference-run.md (understanding function)
    ↓
configuration.md (input options)
    ↓
errors.md (error handling)
```

--------------------------------

### Download Artifact by ID in v4

Source: https://github.com/actions/download-artifact/blob/main/docs/MIGRATION.md

This example demonstrates how to download a specific artifact using its unique ID in v4. This is recommended for security and to avoid potential TOCTOU issues, ensuring you download the exact artifact version you expect.

```yaml
  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 }}
```

--------------------------------

### Upload Artifact with Output in v4

Source: https://github.com/actions/download-artifact/blob/main/docs/MIGRATION.md

In v4, artifacts are immutable by default and each upload gets a unique ID. This example shows how to upload an artifact and capture its unique ID using the `id` and `outputs` properties, making it available to subsequent jobs.

```yaml
jobs:
  upload:
    runs-on: ubuntu-latest

    # Make the artifact ID available to the download job
    outputs:
      artifact-id: ${{ steps.upload-step.outputs.artifact-id }}

    steps:
      - name: Create a file
        run: echo "hello world" > my-file.txt
      - name: Upload Artifact
        id: upload-step
        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-step.outputs.artifact-id }}"
```

--------------------------------

### Download Artifact with Lenient Digest Handling

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/types.md

Example of a GitHub Actions workflow snippet demonstrating how to configure the download-artifact action to use a specific digest mismatch behavior, such as 'warn'.

```yaml
# GitHub Actions workflow
- name: Download with lenient digest handling
  uses: actions/download-artifact@v8
  with:
    name: my-artifact
    digest-mismatch: warn  # Log warning but continue
```

--------------------------------

### User Navigation Pattern

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/INDEX.md

This pattern outlines the recommended document navigation for users writing GitHub Actions workflows, starting from a quick reference and drilling down into specific details.

```markdown
quick-reference.md
    ↓
configuration.md (if more detail needed)
    ↓
action-specification.md (for exact specs)
    ↓
errors.md (if something breaks)
```

--------------------------------

### Download Single Artifact by Name

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/README.md

Example of downloading a single artifact named 'dist' in a GitHub Actions workflow.

```yaml
- name: Build
  run: npm run build

- name: Upload
  uses: actions/upload-artifact@v7
  with:
    name: dist
    path: dist/

- name: Download
  uses: actions/download-artifact@v8
  with:
    name: dist
```

--------------------------------

### Partial Artifact ID Match Warning Example

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/errors.md

This scenario occurs when some, but not all, of the specified artifact IDs are found. A warning is issued, and the action continues to download the found artifacts.

```yaml
- uses: actions/download-artifact@v8
  with:
    artifact-ids: 123,456,789
    # Finds: 123, 456
    # Missing: 789
```

--------------------------------

### None of the Provided Artifact IDs Found Example

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/errors.md

This scenario occurs when none of the artifact IDs specified in the `artifact-ids` input exist in the workflow run. The action will fail.

```yaml
- uses: actions/download-artifact@v8
  with:
    artifact-ids: 999,888,777  # None of these IDs exist
```

--------------------------------

### Conditional Artifact Download

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/quick-reference.md

Conditionally download artifacts based on the GitHub event. This example downloads artifacts matching a pattern only when the event is a 'push'.

```yaml
- uses: actions/download-artifact@v8
  if: github.event_name == 'push'
  with:
    pattern: 'release-*'
    merge-multiple: true
```

--------------------------------

### Markdown Code Block Convention

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/INDEX.md

This convention states that 'markdown' is used for code blocks that display output examples.

```markdown
```markdown
# Example Markdown output

This is a sample output.

- Item 1
- Item 2
```
```

--------------------------------

### YAML Code Block Convention

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/INDEX.md

This convention indicates that 'yaml' is used for code blocks that demonstrate GitHub Actions workflow examples.

```markdown
```yaml
# Example GitHub Actions workflow snippet
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Download artifact
        uses: actions/download-artifact@v3
        with:
          name: my-artifact
```
```

--------------------------------

### Merge Artifacts in v4

Source: https://github.com/actions/download-artifact/blob/main/docs/MIGRATION.md

To achieve the v3 behavior of merging multiple uploads in v4, use the `actions/upload-artifact/merge@v4` action. This example demonstrates uploading individual artifacts with unique names and then merging them into a single artifact named 'all-my-files' using a pattern.

```yaml
jobs:
  upload:
    strategy:
      matrix:
        runs-on: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.runs-on }}
    steps:
      - name: Create a File
        run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: my-artifact-${{ matrix.runs-on }}
          path: file-${{ matrix.runs-on }}.txt
merge:
  runs-on: ubuntu-latest
  needs: upload
  steps:
    - name: Merge Artifacts
      uses: actions/upload-artifact/merge@v4
      with:
        name: all-my-files
        pattern: my-artifact-*
```

--------------------------------

### Upload Multiple Artifacts in v3

Source: https://github.com/actions/download-artifact/blob/main/docs/MIGRATION.md

In v3, multiple uploads to the same artifact name would result in a single archive. This example shows how to upload files from different matrix jobs to a single artifact named 'all-my-files'.

```yaml
jobs:
  upload:
    strategy:
      matrix:
        runs-on: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.runs-on }}
    steps:
      - name: Create a File
        run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
      - name: Upload Artifact
        uses: actions/upload-artifact@v3
        with:
          name: all-my-files # NOTE: same artifact name
          path: file-${{ matrix.runs-on }}.txt
```

--------------------------------

### v3: Multiple uploads to the same artifact name

Source: https://github.com/actions/download-artifact/blob/main/docs/MIGRATION.md

In v3, artifacts are mutable, allowing multiple jobs to upload to the same artifact name. This example shows how different runs-on environments create distinct files within the same artifact.

```yaml
jobs:
  upload:
    strategy:
      matrix:
        runs-on: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.runs-on }}
    steps:
      - name: Create a File
        run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
      - name: Upload Artifact
        uses: actions/upload-artifact@v3
        with:
          name: my-artifact # NOTE: same artifact name
          path: file-${{ matrix.runs-on }}.txt
  download:
    needs: upload
    runs-on: ubuntu-latest
    steps:
      - name: Download All Artifacts
        uses: actions/download-artifact@v3
        with:
          name: my-artifact
          path: my-artifact
      - run: ls -R my-artifact
```

--------------------------------

### Internal Use: Batching Parallel Downloads

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/api-reference-chunk.md

Internal usage example of the chunk function to batch parallel artifact downloads, limiting concurrent downloads to prevent resource exhaustion.

```typescript
const downloadPromises = artifacts.map(artifact => ({
  name: artifact.name,
  promise: artifactClient.downloadArtifact(artifact.id, {...options})
}))

const chunkedPromises = chunk(downloadPromises, PARALLEL_DOWNLOADS)
// PARALLEL_DOWNLOADS = 5

for (const chunkItem of chunkedPromises) {
  const chunkPromises = chunkItem.map(item => item.promise)
  const results = await Promise.all(chunkPromises)
  // Process results before moving to next chunk
}
```

--------------------------------

### Basic Usage (Download All Artifacts)

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/api-reference-run.md

This TypeScript snippet demonstrates the basic usage of the download-artifact action. It reads inputs from the GitHub Actions context, downloads all artifacts to the GITHUB_WORKSPACE, and sets the 'download-path' output.

```typescript
import {run} from './download-artifact'

await run()
// Reads inputs from GitHub Actions context
// Downloads all artifacts to GITHUB_WORKSPACE
// Sets download-path output
```

--------------------------------

### Main Function and Utilities

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/README.md

The main entry point for the action is `run()`, located in `download-artifact.ts`. The `chunk()` utility is used internally for parallel download batching.

```typescript
src/
  ├── download-artifact.ts    # Main function and utilities
  │   ├── run()              # Primary exported function
  │   └── chunk()            # Utility for array chunking
  └── constants.ts           # Type definitions
      ├── Inputs enum
      ├── DigestMismatchBehavior enum
      └── Outputs enum
```

--------------------------------

### run()

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/api-reference-run.md

The main entry point for the download-artifact action. It orchestrates the entire workflow of downloading artifacts from a GitHub Actions workflow run, with support for downloading by name, artifact IDs, or glob patterns.

```APIDOC
## run()

### Description
The `run()` function is the primary exported function from the download-artifact action. It reads GitHub Actions inputs, validates them, retrieves artifact metadata from the Actions artifact API, and downloads the requested artifacts in parallel with digest validation.

### Method
Asynchronous function call

### Parameters
None. All configuration is read from GitHub Actions inputs via `@actions/core.getInput()`.

### Return Type
`Promise<void>`

Resolves when all downloads are complete and outputs are set. Rejects with an Error if any validation fails or if digest validation fails with error behavior.

### Error Handling
The `run()` function throws errors in the following cases:

| Error Condition | Error Message | Thrown At |
|-----------------|---------------|-----------|
| Invalid `digest-mismatch` value | `Invalid value for 'digest-mismatch': '<value>'. Valid options are: ignore, info, warn, error` | Input validation |
| Both `name` and `artifact-ids` provided | `Inputs 'name' and 'artifact-ids' cannot be used together. Please specify only one.` | Input validation |
| Invalid repository format | `Invalid repository: '<value>'. Must be in format owner/repo` | Options preparation |
| Single artifact by name not found | `Artifact '<name>' not found` | Artifact retrieval |
| No valid artifact IDs in input | `No valid artifact IDs provided in 'artifact-ids' input` | ID parsing |
| Invalid artifact ID (non-numeric) | `Invalid artifact ID: '<id>'. Must be a number.` | ID parsing |
| No artifacts found for given IDs | `None of the provided artifact IDs were found` | ID lookup |
| Digest validation failed (error mode) | `Digest validation failed for artifact(s): <names>. Use 'digest-mismatch: warn' to continue on mismatch.` | Post-download validation |

### Behavior by Input Combination

#### Single Artifact by Name
When the `name` input is provided:
- Fetches a single artifact by name using `artifactClient.getArtifact()`
- Downloads directly to the specified path (no subdirectory created)
- Uses artifact digest for hash validation

#### Multiple Artifacts by ID
When the `artifact-ids` input is provided (comma-separated):
- Parses comma-separated list of numeric IDs
- Fetches all artifacts and filters by ID
- Each artifact downloaded to its own subdirectory (named after artifact) unless `merge-multiple: true`
- Warns if any requested IDs are not found
- Throws if none of the requested IDs are found

#### All Artifacts or Pattern-Filtered
When neither `name` nor `artifact-ids` is provided:
- Lists all artifacts in the workflow run
- If `pattern` input is provided, filters by glob pattern using Minimatch
- Each artifact downloaded to its own subdirectory (named after artifact) unless `merge-multiple: true`

#### Download Path Resolution
- If `path` input not provided, defaults to `process.env.GITHUB_WORKSPACE` or `process.cwd()`
- If path starts with `~`, expands to home directory via `os.homedir()`
- Final path is resolved to absolute path via `path.resolve()`

#### Multiple Artifact Destination
- If `merge-multiple: true` or downloading a single artifact, all files extracted to the specified path
- If `merge-multiple: false` and downloading multiple artifacts, each artifact extracted to a subdirectory named after the artifact

#### Parallel Downloads
- Downloads are chunked into groups of 5 concurrent downloads
- Prevents overwhelming the system with too many simultaneous requests
- All downloads in a chunk complete before moving to the next chunk

#### Digest Validation Behavior
Controlled by the `digest-mismatch` input (default: `error`):
- **ignore**: Silently continues even if digest validation fails
- **info**: Logs info-level message if digest validation fails
- **warn**: Logs warning-level message if digest validation fails
- **error**: Collects all digest mismatches and throws error at end (fails the action)

### Environment Variables

| Variable | Usage |
|----------|-------|
| `GITHUB_WORKSPACE` | Default destination path if `path` input not provided |
```

--------------------------------

### ArtifactClient Interface

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/implementation-details.md

Defines the interface for interacting with the artifact API client, including methods for getting, listing, and downloading artifacts.

```typescript
interface ArtifactClient {
  getArtifact(name: string, options?: FindOptions): Promise<GetArtifactResponse>
  listArtifacts(options?: ListOptions): Promise<ListArtifactsResponse>
  downloadArtifact(id: number, options?: DownloadOptions): Promise<DownloadResponse>
}
```

--------------------------------

### Action Entry Point Script

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/implementation-details.md

Shows how the compiled JavaScript entry point imports and executes the main `run` function, with error handling.

```typescript
import { run } from './download-artifact'
run().catch(err => core.setFailed(...))
```

--------------------------------

### Usage of download-path output

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/configuration.md

Demonstrates how to access and use the 'download-path' output in a subsequent workflow step. This output provides the absolute path where artifacts were downloaded.

```yaml
- id: download
  uses: actions/download-artifact@v8
  with:
    path: ./artifacts

- run: |
    echo "Path: ${{ steps.download.outputs.download-path }}"
    ls -R "${{ steps.download.outputs.download-path }}"
```

--------------------------------

### Update Release File

Source: https://github.com/actions/download-artifact/blob/main/CONTRIBUTING.md

Update the main JavaScript entry-point file for the action.

```bash
npm run release
```

--------------------------------

### Run Tests

Source: https://github.com/actions/download-artifact/blob/main/CONTRIBUTING.md

Ensure all project tests pass.

```bash
npm run test
```

--------------------------------

### Matrix strategy for downloading artifacts

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/configuration.md

Uses a matrix strategy to download artifacts tailored for different platforms. The 'pattern' input dynamically selects build artifacts based on the matrix configuration.

```yaml
strategy:
  matrix:
    platform: [ubuntu, macos, windows]

jobs:
  download:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v8
        with:
          pattern: 'build-${{ matrix.platform }}-*'
          merge-multiple: true
          path: ./builds
```

--------------------------------

### run() Return Type

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/api-reference-run.md

The run() function returns a Promise that resolves when all downloads are complete and outputs are set. It rejects with an error if validation fails.

```typescript
Promise<void>
```

--------------------------------

### v3: Overwriting an artifact

Source: https://github.com/actions/download-artifact/blob/main/docs/MIGRATION.md

In v3, artifacts are mutable, allowing subsequent uploads with the same name to overwrite previous content. This example demonstrates uploading a file twice with the same artifact name.

```yaml
jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - name: Create a file
        run: echo "hello world" > my-file.txt
      - name: Upload Artifact
        uses: actions/upload-artifact@v3
        with:
          name: my-artifact # NOTE: same artifact name
          path: my-file.txt
  upload-again:
    needs: upload
    runs-on: ubuntu-latest
    steps:
      - name: Create a different file
        run: echo "goodbye world" > my-file.txt
      - name: Upload Artifact
        uses: actions/upload-artifact@v3
        with:
          name: my-artifact # NOTE: same artifact name
          path: my-file.txt
```

--------------------------------

### Bundling with Vercel NCC

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/implementation-details.md

The command to bundle all dependencies into a single JavaScript file for distribution, using `@vercel/ncc`.

```bash
npm run release  # Uses @vercel/ncc to bundle
```

--------------------------------

### Download all artifacts to current workspace

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/configuration.md

This is the default configuration. It downloads all artifacts to the GITHUB_WORKSPACE directory without requiring any specific inputs.

```yaml
- uses: actions/download-artifact@v8
```

--------------------------------

### run()

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/INDEX.md

The main function for executing core logic. Refer to the run API reference for detailed specifications and flow.

```APIDOC
## run()

### Description
This is the primary function for executing the system's core operations. It orchestrates various tasks based on the provided inputs and configurations.

### Endpoint
N/A (SDK Function)

### Parameters
Refer to `configuration.md` for input specifications and `types.md` for type definitions.

### Response
Refer to `configuration.md` for output specifications and `types.md` for type definitions.

### See Also
- [api-reference-run.md](./api-reference-run.md)
- [configuration.md](./configuration.md)
- [types.md](./types.md)
```

--------------------------------

### Digest Validation Failed (Error Mode) Example

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/errors.md

This scenario occurs when an artifact fails digest validation and the `digest-mismatch` input is set to `error` (the default). The action will fail if any artifact's digest does not match the expected value.

```yaml
- uses: actions/download-artifact@v8
  with:
    name: my-artifact
    digest-mismatch: error  # Default, fails on mismatch
```

--------------------------------

### Setting Download Path Output

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/types.md

Illustrates how the 'run()' function in the download-artifact action sets the 'download-path' output using the Outputs enum. This makes the download location available to subsequent workflow steps.

```typescript
import {Outputs} from './constants'
import * as core from '@actions/core'

core.setOutput(Outputs.DownloadPath, resolvedPath)
// Equivalent to:
// core.setOutput('download-path', resolvedPath)
```

--------------------------------

### run() Function Signature

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/api-reference-run.md

The main exported function for the download-artifact action. It orchestrates the entire artifact download process.

```typescript
export async function run(): Promise<void>
```

--------------------------------

### Download Multiple Artifacts with Pattern and Merge

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/README.md

Collects outputs from matrix builds by downloading all artifacts matching the 'build-*' pattern and merging them into a single directory.

```yaml
strategy:
  matrix: 
    os: [ubuntu, macos, windows]

- name: Build
  run: npm run build

- name: Upload
  uses: actions/upload-artifact@v7
  with:
    name: build-${{ matrix.os }}
    path: dist/

# Later job
- name: Download All
  uses: actions/download-artifact@v8
  with:
    pattern: 'build-*'
    merge-multiple: true
```

--------------------------------

### Download with Pattern Filter

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/api-reference-run.md

This YAML snippet demonstrates downloading artifacts that match a specified pattern using the download-artifact action. The 'merge-multiple' option is set to true, and artifacts are saved to the specified path.

```yaml
- name: Download matching artifacts
  uses: actions/download-artifact@v8
  with:
    pattern: 'build-*'
    merge-multiple: true
    path: ./builds
```

--------------------------------

### Mocking Modules for Testing

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/implementation-details.md

Lists the key modules that are mocked in the test suite to isolate and test specific functionalities of the download artifact action.

```typescript
// Mocked modules
@actions/core         // Input/output functions
@actions/artifact     // Artifact API client
@actions/github       // GitHub context
```

--------------------------------

### Single Artifact Download Implementation

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/implementation-details.md

Handles the download of a single artifact when the 'name' input is provided. Fetches artifact metadata and prepares it for download.

```typescript
if (isSingleArtifactDownload) {
  core.info(`Downloading single artifact`)
  
  const {artifact: targetArtifact} = await artifactClient.getArtifact(
    inputs.name,
    options
  )
  
  if (!targetArtifact) {
    throw new Error(`Artifact '${inputs.name}' not found`)
  }
  
  artifacts = [targetArtifact]
}
```

--------------------------------

### Download All Artifacts to Current Directory

Source: https://github.com/actions/download-artifact/blob/main/README.md

Downloads all artifacts to the current working directory. Each artifact will be placed in its own subdirectory.

```yaml
steps:
- uses: actions/download-artifact@v8
- name: Display structure of downloaded files
  run: ls -R
```

--------------------------------

### In GitHub Actions Workflow

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/api-reference-run.md

This YAML snippet shows how to use the download-artifact action in a GitHub Actions workflow to download all artifacts to a specified path.

```yaml
- name: Download artifacts
  uses: actions/download-artifact@v8
  with:
    path: ./downloads
```

--------------------------------

### Download Artifacts by Pattern or All

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/implementation-details.md

Handles downloading artifacts when a pattern is provided for filtering or when no specific filters are set, in which case all artifacts are downloaded. Uses Minimatch for pattern matching.

```typescript
else {
  // List all artifacts
  const listArtifactResponse = await artifactClient.listArtifacts({
    latest: true,
    ...options
  })
  artifacts = listArtifactResponse.artifacts
  
  // Apply pattern filter if provided
  if (inputs.pattern) {
    core.info(`Filtering artifacts by pattern '${inputs.pattern}'`)
    const matcher = new Minimatch(inputs.pattern)
    artifacts = artifacts.filter(artifact => matcher.match(artifact.name))
  } else {
    core.info(
      'No input name, artifact-ids or pattern filtered specified, downloading all artifacts'
    )
  }
}
```

--------------------------------

### Handle Digest Mismatch with Warning

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/action-specification.md

Configure the action to log a warning instead of failing when a digest mismatch is detected after download. This helps in identifying potential corruption issues.

```yaml
- uses: actions/download-artifact@v8
  with:
    digest-mismatch: warn  # Log warning, don't fail
```

--------------------------------

### Download All Artifacts to Specific Directory

Source: https://github.com/actions/download-artifact/blob/main/README.md

Downloads all artifacts into a specified directory. Each artifact will be placed in its own subdirectory within the target path.

```yaml
steps:
- uses: actions/download-artifact@v8
  with:
    path: path/to/artifacts
- name: Display structure of downloaded files
  run: ls -R path/to/artifacts
```

--------------------------------

### Download Artifact by Name and Path

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/README.md

Download a specific artifact by its name and specify a custom path for extraction. This is useful for organizing downloaded artifacts.

```yaml
- uses: actions/download-artifact@v8
  with:
    name: my-artifact
    path: ./output
```

--------------------------------

### Download Artifacts to Custom Path

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/quick-reference.md

Specifies a custom destination directory for downloaded artifacts. This option can be used with any download mode. The path can include '~' to refer to the user's home directory. The default destination is $GITHUB_WORKSPACE.

```yaml
- uses: actions/download-artifact@v8
  with:
    path: ./custom/destination
```

--------------------------------

### Minimatch Usage

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/implementation-details.md

Demonstrates how to use the Minimatch library for glob pattern matching against names.

```typescript
const matcher = new Minimatch(pattern)
const isMatch = matcher.match(name)  // boolean
```

--------------------------------

### Download Artifacts Matching a Pattern

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/action-specification.md

Use a glob pattern to download multiple artifacts. This is only applied when an artifact name is not specified and matches against the artifact name.

```yaml
- uses: actions/download-artifact@v8
  with:
    pattern: 'release-*'
```

--------------------------------

### Download Single Artifact to Specific Directory

Source: https://github.com/actions/download-artifact/blob/main/README.md

Downloads a single artifact named 'my-artifact' to a specified destination directory. Supports tilde expansion for paths.

```yaml
steps:
- uses: actions/download-artifact@v8
  with:
    name: my-artifact
    path: your/destination/dir
- name: Display structure of downloaded files
  run: ls -R your/destination/dir
```

--------------------------------

### Download Artifacts by IDs

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/implementation-details.md

Handles downloading artifacts when a list of specific IDs is provided. It parses, validates, and filters artifact IDs before initiating the download.

```typescript
if (isDownloadByIds) {
  core.info(`Downloading artifacts by ID`)
  
  // Parse comma-separated IDs
  const artifactIdList = inputs.artifactIds
    .split(',')
    .map(id => id.trim())
    .filter(id => id !== '')
  
  // Validate all are numeric
  artifactIds = artifactIdList.map(id => {
    const numericId = parseInt(id, 10)
    if (isNaN(numericId)) {
      throw new Error(`Invalid artifact ID: '${id}'. Must be a number.`) 
    }
    return numericId
  })
  
  // List all and filter
  const listArtifactResponse = await artifactClient.listArtifacts({
    latest: true,
    ...options
  })
  
  artifacts = listArtifactResponse.artifacts.filter(artifact =>
    artifactIds.includes(artifact.id)
  )
  
  // Check results
  if (artifacts.length === 0) {
    throw new Error(`None of the provided artifact IDs were found`)
  }
  
  if (artifacts.length < artifactIds.length) {
    const foundIds = artifacts.map(a => a.id)
    const missingIds = artifactIds.filter(id => !foundIds.includes(id))
    core.warning(
      `Could not find the following artifact IDs: ${missingIds.join(', ')}`
    )
  }
}
```

--------------------------------

### Download Single Artifact to Current Directory

Source: https://github.com/actions/download-artifact/blob/main/README.md

Downloads a single artifact named 'my-artifact' to the default working directory. This is useful for basic artifact retrieval.

```yaml
steps:
- uses: actions/download-artifact@v8
  with:
    name: my-artifact
- name: Display structure of downloaded files
  run: ls -R
```

--------------------------------

### Download Mode Selection Logic

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/implementation-details.md

Determines the download mode based on input values. Supports single artifact by name, multiple by ID, or all/filtered artifacts.

```typescript
const isSingleArtifactDownload = !!inputs.name
const isDownloadByIds = !!inputs.artifactIds
```

--------------------------------

### Download All Artifacts with Pattern

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/configuration.md

Use this snippet to download all artifacts from a workflow run, optionally filtering them by a glob pattern. Files can be merged into a single directory or placed in separate subdirectories.

```yaml
- uses: actions/download-artifact@v8
  with:
    pattern: 'build-*'
    merge-multiple: true
```

--------------------------------

### Download All Artifacts to the Same Directory

Source: https://github.com/actions/download-artifact/blob/main/README.md

Downloads all artifacts into a single, specified directory, merging their contents. This overwrites files with the same name from different artifacts.

```yaml
steps:
- uses: actions/download-artifact@v8
  with:
    path: path/to/artifacts
    merge-multiple: true
- name: Display structure of downloaded files
  run: ls -R path/to/artifacts
```

--------------------------------

### Download Matrix Build Artifacts

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/quick-reference.md

Downloads artifacts generated by a matrix build strategy, filtering by a pattern that includes the matrix job identifier. Artifacts are downloaded to a specified path.

```yaml
strategy:
  matrix:
    os: [ubuntu, macos, windows]

- uses: actions/download-artifact@v8
  with:
    pattern: 'build-${{ matrix.os }}-*'
    path: ./builds
```

--------------------------------

### Logging Levels

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/implementation-details.md

Illustrates the different logging levels available through the `@actions/core` module for user-visible information, warnings, and debug messages.

```typescript
core.info()      // User-visible information
core.warning()   // Warning conditions
core.debug()     // Diagnostic information (only shown in debug mode)
```

--------------------------------

### Download Artifact with Custom Path and Digest Mismatch Handling

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/action-specification.md

Use this snippet to download artifacts to a custom path and control how digest mismatches are handled. The `digest-mismatch` input can be set to 'warn' to log a warning instead of failing the workflow.

```yaml
- uses: actions/download-artifact@v8
  with:
    path: ./my-artifacts
    digest-mismatch: warn
```

--------------------------------

### Download Artifacts by ID

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/README.md

Download multiple specific artifacts using their unique numeric IDs. Separate IDs with commas.

```yaml
- uses: actions/download-artifact@v8
  with:
    artifact-ids: 12345,67890
```

--------------------------------

### Download Filtered Artifacts to Same Directory

Source: https://github.com/actions/download-artifact/blob/main/README.md

Downloads artifacts matching a pattern into a single directory. Useful for consolidating artifacts from matrix builds.

```yaml
jobs:
  upload:
    strategy:
      matrix:
        runs-on: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.runs-on }}
    steps:
    - name: Create a File
      run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
    - name: Upload Artifact
      uses: actions/upload-artifact@v7
      with:
        name: my-artifact-${{ matrix.runs-on }}
        path: file-${{ matrix.runs-on }}.txt
  download:
    needs: upload
    runs-on: ubuntu-latest
    steps:
    - name: Download All Artifacts
      uses: actions/download-artifact@v8
      with:
        path: my-artifact
        pattern: my-artifact-*
        merge-multiple: true
    - run: ls -R my-artifact
```

--------------------------------

### Set Download Path Output

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/types.md

Sets the resolved download path as an output. This value is always set, even if no artifacts are downloaded.

```typescript
const resolvedPath = path.resolve(inputs.path)
core.setOutput(Outputs.DownloadPath, resolvedPath)
```

--------------------------------

### Download Multiple Artifacts by ID

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/api-reference-run.md

This YAML snippet shows how to download multiple artifacts by providing their IDs to the download-artifact action. The artifacts are saved to the specified path.

```yaml
- name: Download artifacts by ID
  uses: actions/download-artifact@v8
  with:
    artifact-ids: 12345,67890
    path: ./artifacts
```

--------------------------------

### Download Artifacts by Pattern

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/quick-reference.md

Downloads artifacts whose names match a specified glob pattern. This is useful for filtering artifacts when you don't know the exact names or IDs. If the 'name' input is also specified, this 'pattern' input is ignored.

```yaml
- uses: actions/download-artifact@v8
  with:
    pattern: 'build-*'
```

--------------------------------

### Download Artifact by Name

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/quick-reference.md

Downloads a single, specific artifact by its exact name. The artifact is extracted directly into the GITHUB_WORKSPACE. An error will occur if the artifact with the specified name does not exist.

```yaml
- uses: actions/download-artifact@v8
  with:
    name: artifact-name
```

--------------------------------

### Format Code

Source: https://github.com/actions/download-artifact/blob/main/CONTRIBUTING.md

Format code according to project standards.

```bash
npm run format
```

--------------------------------

### Download Cross-Repository Artifact with Custom Settings

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/action-specification.md

Use this snippet to download an artifact from a different repository within your organization. You need to provide a GitHub token with appropriate permissions and specify the repository and run ID.

```yaml
- uses: actions/download-artifact@v8
  with:
    name: shared-lib
    github-token: ${{ secrets.GH_PAT }}
    repository: myorg/shared-repo
    run-id: 9876543210
    path: ./vendor
```

--------------------------------

### Extract Multiple Downloaded Artifacts Separately

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/action-specification.md

When downloading multiple artifacts, 'merge-multiple' defaults to false, extracting each artifact into its own subdirectory within the specified 'path'.

```yaml
- uses: actions/download-artifact@v8
  with:
    pattern: 'build-*'
    merge-multiple: false
```

--------------------------------

### Process Download Batches

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/implementation-details.md

Iterates through batched download promises, processes them in parallel using Promise.all, and collects results, including any digest mismatches.

```typescript
const digestMismatches: string[] = []

for (const chunkItem of chunkedPromises) {
  const chunkPromises = chunkItem.map(item => item.promise)
  const results = await Promise.all(chunkPromises)
  
  for (let i = 0; i < results.length; i++) {
    const outcome = results[i]
    const artifactName = chunkItem[i].name
    
    if (outcome.digestMismatch) {
      digestMismatches.push(artifactName)
      // Handle per configuration
    }
  }
}
```

--------------------------------

### Download multiple named artifacts matching a pattern

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/configuration.md

Downloads multiple artifacts whose names match a given pattern. The 'merge-multiple: true' option combines them into a single directory structure at the specified path.

```yaml
- uses: actions/download-artifact@v8
  with:
    pattern: 'build-*'
    path: ./builds
    merge-multiple: true
```

--------------------------------

### Usage of Inputs Enum

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/types.md

Demonstrates how to use the Inputs enum to retrieve input values from the GitHub Actions context in TypeScript. Ensure necessary imports are included.

```typescript
import {Inputs} from './constants'
import * as core from '@actions/core'

const inputs = {
  name: core.getInput(Inputs.Name, {required: false}),
  path: core.getInput(Inputs.Path, {required: false}),
  token: core.getInput(Inputs.GitHubToken, {required: false}),
  // ... etc
}
```

--------------------------------

### Access Downloaded Artifact Path

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/quick-reference.md

Retrieves the path where artifacts were downloaded. This output is always set, even if no artifacts were found. Use the `steps.<id>.outputs.download-path` syntax to access it in subsequent workflow steps.

```yaml
- id: download
  uses: actions/download-artifact@v8
  with:
    path: ./artifacts

- run: ls -R "${{ steps.download.outputs.download-path }}"
```

--------------------------------

### Chunking Download Promises

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/README.md

The `chunk()` utility splits artifact downloads into batches of 5 to prevent resource exhaustion while maintaining concurrency. Process results before the next batch.

```typescript
const chunkedPromises = chunk(downloadPromises, 5)
for (const batch of chunkedPromises) {
  const results = await Promise.all(batch)
  // Process results before next batch
}
```

--------------------------------

### Download Artifact with GitHub Token

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/action-specification.md

Use this snippet when downloading artifacts from a different repository or workflow run. It requires a GitHub token with read permissions.

```yaml
- uses: actions/download-artifact@v8
  with:
    github-token: ${{ secrets.GH_PAT }}
    repository: owner/other-repo
    run-id: 123456
```

--------------------------------

### Maintainer Navigation Pattern

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/INDEX.md

This pattern describes the documentation journey for maintainers, focusing on architecture, main function, type system, error handling, and input configuration.

```markdown
implementation-details.md (architecture)
    ↓
api-reference-run.md (main function)
    ↓
types.md (type system)
    ↓
errors.md (error handling)
    ↓
configuration.md (input handling)
```

--------------------------------

### v4: Handling multiple uploads to the same artifact name

Source: https://github.com/actions/download-artifact/blob/main/docs/MIGRATION.md

In v4, artifacts are immutable. To achieve similar behavior to v3's multiple uploads, use unique artifact names per upload and employ `pattern` and `merge-multiple` inputs for downloading.

```diff
jobs:
  upload:
    strategy:
      matrix:
        runs-on: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.runs-on }}
    steps:
    - name: Create a File
      run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
    - name: Upload Artifact
-     uses: actions/upload-artifact@v3
+     uses: actions/upload-artifact@v4
      with:
-       name: my-artifact
+       name: my-artifact-${{ matrix.runs-on }}
        path: file-${{ matrix.runs-on }}.txt
  download:
    needs: upload
    runs-on: ubuntu-latest
    steps:
    - name: Download All Artifacts
-     uses: actions/download-artifact@v3
+     uses: actions/download-artifact@v4
      with:
-       name: my-artifact
        path: my-artifact
+       pattern: my-artifact-*
+       merge-multiple: true
    - run: ls -R my-artifact
```

--------------------------------

### Download Multiple Artifacts by IDs

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/quick-reference.md

Downloads multiple artifacts specified as a comma-separated list of numeric IDs. Each artifact is placed in its own subdirectory, though they might be merged depending on other configurations. A warning is issued if some of the specified IDs are not found.

```yaml
- uses: actions/download-artifact@v8
  with:
    artifact-ids: 12345,67890,11111
```

--------------------------------

### Download Artifact from Specific Repository

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/action-specification.md

Specify a target repository for artifact downloads when a GitHub token is provided. The format must be 'owner/repo'.

```yaml
- uses: actions/download-artifact@v8
  with:
    github-token: ${{ secrets.GH_PAT }}
    repository: myorg/myrepo
```

--------------------------------

### Download Single Artifact by Name

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/configuration.md

Use this snippet to download a specific artifact by its name. The artifact is extracted directly to the specified path.

```yaml
- uses: actions/download-artifact@v8
  with:
    name: my-artifact
```

--------------------------------

### Input Type Definitions

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/implementation-details.md

Lists the expected input types for the action, including literal strings, boolean flags, and numeric strings that are parsed.

```typescript
const inputs = {
  name: string,
  artifact-ids: string,
  path: string,
  pattern: string,
  merge-multiple: boolean,                        // Via getBooleanInput()
  github-token: string,
  repository: string,
  runID: number,                                  // Via parseInt()
  skip-decompress: boolean,                       // Via getBooleanInput()
  digest-mismatch: DigestMismatchBehavior  // Enum string
}
```

--------------------------------

### Update Licensed Dependency Cache

Source: https://github.com/actions/download-artifact/blob/main/CONTRIBUTING.md

Update the cache for third-party dependencies using the Licensed tool.

```bash
licensed cache
```

--------------------------------

### Reading Inputs with @actions/core

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/implementation-details.md

Collects and reads all inputs for the action using the @actions/core library. Ensures required inputs are handled and optional inputs have fallbacks.

```typescript
const inputs = {
  name: core.getInput(Inputs.Name, {required: false}),
  path: core.getInput(Inputs.Path, {required: false}),
  token: core.getInput(Inputs.GitHubToken, {required: false}),
  repository: core.getInput(Inputs.Repository, {required: false}),
  runID: parseInt(core.getInput(Inputs.RunID, {required: false})),
  pattern: core.getInput(Inputs.Pattern, {required: false}),
  mergeMultiple: core.getBooleanInput(Inputs.MergeMultiple, {
    required: false
  }),
  artifactIds: core.getInput(Inputs.ArtifactIds, {required: false}),
  skipDecompress: core.getBooleanInput(Inputs.SkipDecompress, {
    required: false
  }),
  digestMismatch: (core.getInput(Inputs.DigestMismatch, {required: false}) ||
    DigestMismatchBehavior.Error) as DigestMismatchBehavior
}
```

--------------------------------

### Download Artifact from Other Repository

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/README.md

Download a specific artifact from a different repository within your GitHub organization or a public repository. Requires a GitHub token and the source repository and run ID.

```yaml
- uses: actions/download-artifact@v8
  with:
    name: artifact
    github-token: ${{ secrets.GH_PAT }}
    repository: owner/repo
    run-id: 123456
```

--------------------------------

### Chunk Array of Objects

Source: https://github.com/actions/download-artifact/blob/main/_autodocs/api-reference-chunk.md

Shows how to chunk an array of objects. Each inner array (chunk) will contain objects up to the specified chunk size.

```typescript
import {chunk} from './download-artifact'

const items = [
  {id: 1, name: 'A'},
  {id: 2, name: 'B'},
  {id: 3, name: 'C'},
  {id: 4, name: 'D'}
]

const result = chunk(items, 2)
// Result: [
//   [{id: 1, name: 'A'}, {id: 2, name: 'B'}],
//   [{id: 3, name: 'C'}, {id: 4, name: 'D'}]
// ]
```

--------------------------------

### Download Single Artifact by ID to Specific Directory

Source: https://github.com/actions/download-artifact/blob/main/README.md

Downloads a single artifact using its ID to a specified destination directory. The artifact contents are extracted directly to the path.

```yaml
steps:
- uses: actions/download-artifact@v8
  with:
    artifact-ids: 12345
    path: your/destination/dir
- name: Display structure of downloaded files
  run: ls -R your/destination/dir
```