Share Files and State Between GitHub Actions Jobs

Share files between GitHub Actions jobs with upload-artifact and download-artifact, pass small values with job outputs, and know when caching is the wrong tool.

Published

At a glance

Last reviewed
Versions referenced
actions/checkout@v7 actions/upload-artifact@v7 actions/download-artifact@v8 actions/cache@v6
Reading time
4 min read

Code samples are not run in a live repository. See our editorial standards.

On this page

To share files between GitHub Actions jobs, upload them with actions/upload-artifact in the upstream job and fetch them with actions/download-artifact in a downstream job that declares needs. Each job runs on a fresh runner, so nothing on disk survives unless you upload it. For short strings such as a version or a flag, use job outputs instead of files.

Upload and download artifacts

Upload in one job, then download in a job that depends on it.

name: build-and-test

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [18, 20]
    steps:
      - uses: actions/checkout@v7

      - name: Build application
        run: |
          mkdir -p dist
          echo "Build output for Node ${{ matrix.node }}" > dist/app.txt

      - name: Upload build artifact
        uses: actions/upload-artifact@v7
        with:
          name: app-dist-node-${{ matrix.node }}
          path: dist/
          retention-days: 5

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download Node 20 artifact
        uses: actions/download-artifact@v8
        with:
          name: app-dist-node-20
          path: dist-node-20

      - name: Verify downloaded content
        run: ls -la dist-node-20

The needs: build line makes deploy wait for every matrix leg of build. Without it, the jobs run in parallel and the download step finds nothing.

To verify, open the deploy job and check that the Verify downloaded content step lists app.txt. You can also open the run summary and confirm both app-dist-node-18 and app-dist-node-20 appear under Artifacts.

Use unique names for matrix jobs

Artifacts in upload-artifact v4 and later are immutable. You cannot upload twice to the same artifact name within a run, so matrix legs must each get a distinct name. Interpolate a matrix value such as ${{ matrix.node }} or ${{ matrix.os }} into name.

If you omit name, the artifact is called artifact. Two legs that both omit it collide.

Set retention

retention-days controls how long GitHub keeps the artifact. It cannot exceed the maximum set in your repository, organization or enterprise settings. If you omit it, the repository default applies. Use a short value for intermediate build files so they don’t accumulate in storage.

Download many artifacts at once

Use pattern to select several artifacts, and merge-multiple: true to place all their files in one directory.

name: build-and-collect
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        target: [linux, macos, windows]
    steps:
      - uses: actions/checkout@v7
      - name: Build binary
        run: |
          mkdir -p dist
          echo "artifact for ${{ matrix.target }}" > dist/binary-${{ matrix.target }}.txt
      - uses: actions/upload-artifact@v7
        with:
          name: build-output-${{ matrix.target }}
          path: dist/

  aggregate:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v8
        with:
          pattern: build-output-*
          path: all-builds/
          merge-multiple: true
      - name: Verify files
        run: ls -la all-builds/

Without merge-multiple, each artifact is extracted into its own subdirectory named after the artifact. With it, files land directly in all-builds/. If two artifacts contain a file with the same path, one overwrites the other, so keep file names distinct per matrix leg as above.

To verify, check that the Verify files step lists binary-linux.txt, binary-macos.txt and binary-windows.txt.

Pass small values with job outputs

Use job outputs for strings, IDs and flags. No file is uploaded.

jobs:
  generate_version:
    runs-on: ubuntu-latest
    outputs:
      build_version: ${{ steps.set_version.outputs.version }}
      environment: ${{ steps.set_env.outputs.target_env }}
    steps:
      - id: set_version
        run: echo "version=1.4.2" >> "$GITHUB_OUTPUT"
      - id: set_env
        run: echo "target_env=staging" >> "$GITHUB_OUTPUT"

  deploy:
    runs-on: ubuntu-latest
    needs: generate_version
    steps:
      - name: Print output values
        run: |
          echo "Deploying version ${{ needs.generate_version.outputs.build_version }}"
          echo "Target environment is ${{ needs.generate_version.outputs.environment }}"

Steps write name=value lines to the file at $GITHUB_OUTPUT. The step needs an id so the job-level outputs map can reference steps.<id>.outputs.<name>. The consuming job reads the value from needs.<job_id>.outputs.<name>, and it must list the producer in needs. Use needs: [job1, job2] for several producers. For a related walkthrough, see Run GitHub Actions Jobs Only When Specific Files Change.

If you forget needs, the expression resolves to an empty string. To verify, read the Print output values step log. It should print Deploying version 1.4.2 and Target environment is staging.

Don’t interpolate untrusted values, such as pull request titles or branch names, directly into run: scripts with ${{ }}. Pass them through an env: entry and reference the shell variable instead.

Don’t use the cache to pass files between jobs

actions/cache is for speeding up runs by reusing files that you can regenerate, such as package manager downloads. It is not a delivery mechanism. A cache entry can be evicted when the repository exceeds its cache storage limit (10 GB by default), and a restore can miss.

- name: Restore pip cache
  uses: actions/cache@v6
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
    restore-keys: |
      ${{ runner.os }}-pip-

If the exact key matches, the entry is restored. Otherwise the action falls back to the newest entry matching a restore-keys prefix. Your steps must still work after a miss.

Choose by purpose:

Need Use
Pass build output to a later job in the same run Artifact
Keep files for download after the run Artifact
Pass a version string or flag Job output
Reuse dependencies across runs Cache

To check whether a cache was used, open the actions/cache step log, or use its cache-hit output in a later step condition.

Migrate from v3 to v4 artifacts

The v3 artifact actions are deprecated, and v3 and v4 use different backends. Artifacts uploaded with upload-artifact@v4 or later cannot be downloaded with download-artifact@v3, and the reverse is also true. Upgrade the upload and download steps together.

Behavior changes that break existing workflows:

  • Immutability: v4 does not let you add to an artifact that already exists. v3 merged uploads that shared a name.
  • Matrix uploads: each leg needs a unique name, as shown above.
  • Download without name: v4 extracts each artifact into its own subdirectory. Add merge-multiple: true to restore the flat v3 layout.

Typical failure: a matrix job that uploads every leg as build-output now fails on the second upload. Append a matrix value to the name. The second symptom is a download-artifact@v3 step that cannot find an artifact uploaded with v4. Search .github/workflows/ for @v3 on both actions and update them.

To verify the migration, rerun the workflow. Every upload step should pass, the run summary should list one artifact per matrix leg, and each download step should extract the expected files.

Full example: build then deploy

This .github/workflows/deploy.yml passes both a version string and a build directory to the deploy job.

name: Build and Deploy

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      app_version: ${{ steps.version.outputs.app_version }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v7

      - name: Generate build metadata
        id: version
        run: |
          BUILD_TAG="v1.0.${{ github.run_number }}"
          echo "app_version=$BUILD_TAG" >> "$GITHUB_OUTPUT"

      - name: Build assets
        env:
          BUILD_TAG: ${{ steps.version.outputs.app_version }}
        run: |
          mkdir dist
          echo "Build artifacts for $BUILD_TAG" > dist/app.bundle.js

      - name: Upload build artifacts
        uses: actions/upload-artifact@v7
        with:
          name: build-assets
          path: dist/
          retention-days: 1

  deploy:
    runs-on: ubuntu-latest
    needs: build
    environment: production
    steps:
      - name: Download build artifacts
        uses: actions/download-artifact@v8
        with:
          name: build-assets
          path: dist/

      - name: Deploy package
        run: |
          echo "Deploying version ${{ needs.build.outputs.app_version }}"
          ls -la dist/

Shell variables do not carry over between steps, so the Build assets step reads the tag from the step output through env:. The deploy job reads the same value through needs.build.outputs.app_version.

To verify, open the Deploy package step in the deploy job. The log should print Deploying version v1.0. followed by the run number, and ls should show app.bundle.js in dist/. The environment: production line applies any protection rules configured for that environment, so the job may wait for approval before it starts.

Spotted an error? Report it on our Contact page and see our editorial standards for how we correct articles.