# gh run download: Fetch Workflow Artifacts

> gh run download retrieves artifacts uploaded by a workflow run. Reference for --name, --dir, --pattern, and the no-artifacts and auth errors in CI.

Source: https://latchkey.dev/learn/command-reference/gh-run-download  
Updated: 2026-06-30

gh run download downloads the artifacts produced by a workflow run into a local directory.

When one workflow builds and another consumes, gh run download moves artifacts across runs without the upload/download actions tying you to the same workflow.

## What it does

gh run download fetches artifacts from a specific workflow run, or prompts for a recent run when no ID is given. --name selects one artifact, --pattern matches several, and --dir sets the destination.

## Common usage

```Terminal
gh run download 1234567890
gh run download 1234567890 --name build-output
gh run download 1234567890 --pattern "coverage-*" --dir ./reports
```

## Flags

| Flag | What it does |
| --- | --- |
| -n, --name <name> | Download a specific named artifact (repeatable) |
| -p, --pattern <glob> | Download artifacts matching the glob |
| -D, --dir <dir> | Directory to extract artifacts into |
| <run-id> | The workflow run to download from |
| -R, --repo <owner/repo> | Target a specific repository |

## In CI

Set GH_TOKEN and permissions: { actions: read }. A run ID is required when non-interactive, since the interactive picker cannot run on a headless runner. Artifacts expire after the repository retention period, so an old run may have none left.

## Common errors in CI

"no valid artifacts found to download" means the run produced none or they expired. "run ... not found" means a wrong ID or repository. "gh: To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable" means GH_TOKEN is unset; non-interactive runs also fail without an explicit run ID.

## Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

```.github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### gh run download: Fetch Workflow Artifacts?

When one workflow builds and another consumes, gh run download moves artifacts across runs without the upload/download actions tying you to the same workflow.

### What it does?

gh run download fetches artifacts from a specific workflow run, or prompts for a recent run when no ID is given. --name selects one artifact, --pattern matches several, and --dir sets the destination.

### In CI?

Set GH_TOKEN and permissions: { actions: read }. A run ID is required when non-interactive, since the interactive picker cannot run on a headless runner. Artifacts expire after the repository retention period, so an old run may have none left.

### Common errors in CI?

"no valid artifacts found to download" means the run produced none or they expired. "run ... not found" means a wrong ID or repository. "gh: To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable" means GH_TOKEN is unset; non-interactive runs also fail without an explicit run ID.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt