Skip to content
compiler.dev
Start free

What Is an Artifact in GitHub Actions?

Last updated

An artifact in GitHub Actions is a file or folder that a workflow run saves so that later jobs, or people, can use it. Typical artifacts are build outputs, test reports, coverage files and screenshots from failed end-to-end tests.

How it works

You upload with actions/upload-artifact and download with actions/download-artifact. Because each job runs on a fresh runner, artifacts are the standard way to pass build output from one job to the next. Uploaded artifacts also appear on the workflow run page, where anyone with access can download them as a zip.

Artifacts belong to a single workflow run and expire after a retention period. The default is set at repository or organization level and can be overridden per upload with retention-days.

Since version 4 of the artifact actions, artifact names must be unique within a run. Uploading twice to the same name fails unless you set overwrite. Matrix jobs therefore need a name that includes the matrix value.

Example

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
          retention-days: 7
          if-no-files-found: error

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/
      - run: ls dist

Add if: always() or if: failure() to the upload step to keep reports from failed runs, which is when you need them most.

Artifacts versus caches

ArtifactCache
PurposeOutput of this runSpeed up future runs
ScopeOne workflow runShared across runs and branches by key
RetentionSet per runEvicted when unused or over size limit
ImmutablePer name in a runPer cache key

If you are saving node_modules to reuse next week, use a cache. If you are handing a binary to the deploy job, use an artifact. See GitHub Actions caching.

Common mistakes

  • Uploading too much. Large artifacts slow jobs and count against storage quota. Upload only what is needed.
  • Name collisions in matrix jobs. Include ${{ matrix.os }} or the shard number in the name, and merge afterward with actions/upload-artifact/merge.
  • Secrets in artifacts. Anyone who can read the run can download them. Never upload .env files or credentials.
  • Using artifacts as a cache. It re-uploads every run and is slower than a proper cache.
  • Forgetting retention. Long defaults quietly consume storage.

Related terms

FAQ

How long are artifacts kept?

For the configured retention period, by default 90 days for public repositories unless changed. Check your repository settings for the current value.

Can artifacts be shared between workflows?

Yes, with download-artifact using the run-id and a token, or via the REST API. Within one run it is simple.

Do artifacts cost money?

Storage beyond your plan's included amount is billed. Check GitHub's billing page for current rates.

Related