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.
At a glance
- Last reviewed
- Versions referenced
actions/checkout@v7actions/upload-artifact@v7actions/download-artifact@v8actions/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. Addmerge-multiple: trueto 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.