Managing Workflow Artifacts
1. Uploading Artifacts
| Property | Description | Values | Notes |
|---|---|---|---|
| name | Name of the artifact | string |
Required. Used in the UI to identify the artifact. |
| path | Path to the file or directory to upload | string or array |
Required. Can be a single file or directory, or an array of paths. |
| retention-days | Number of days to retain the artifact | integer |
Optional. Default is 90 days for public repos, 1 day for private. |
| if-no-files-found | Behavior when no files match the path | error, warn, ignore |
Optional. Default is error. |
Example: Upload a single file
steps:
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: my-artifact
path: build/output.txtExample: Upload multiple files
steps:
- name: Upload artifacts
uses: actions/upload-artifact@v4
with:
name: build-artifacts
path: |
build/
dist/
logs/
Note: Artifacts are stored in the cloud and can be downloaded from the GitHub UI or via API. The retention period is configurable.
2. Downloading Artifacts
| Option | Values | Notes |
|---|---|---|
| github.download-artifact | actions/download-artifact@v4 |
Latest stable version of the download action |
Example: Download a Single Artifact
name: Download Artifact
on:
push:
branches: [ main ]
jobs:
download:
runs-on: ubuntu-latest
steps:
- name: Download artifact
uses: actions/download-artifact@v4
with:
name: my-artifact
path: ./downloads/
Example: Download All Artifacts
name: Download All Artifacts
on:
push:
branches: [ main ]
jobs:
download:
runs-on: ubuntu-latest
steps:
- name: Download all artifacts
uses: actions/download-artifact@v4
with:
path: ./artifacts/
Note: Artifacts are only available for workflows that have run successfully. Failed workflows will not have artifacts available for download.
3. Setting Artifact Retention
| Property | Values | Description |
|---|---|---|
| retention-days | 30 |
Number of days to retain artifacts (default: 90) |
| retention-policy | delete |
Policy for handling expired artifacts (default: delete) |
Example: Configure artifact retention in workflow
name: Build and Deploy
on:
push:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Build project
run: npm run build
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: build-artifacts
path: dist/
retention-days: 30
Note: Artifact retention is applied per workflow run, not globally.
4. Naming Artifacts
| Property | Description | Example |
|---|---|---|
| name | The name of the artifact to be created | my-artifact |
| path | The path to the file or directory to be uploaded | dist/ |
| retention-days | Number of days to retain the artifact (default: 90) | 30 |
Example: Upload Artifact with Custom Name
name: Upload Artifact
on:
push:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Upload Artifact
uses: actions/upload-artifact@v3
with:
name: my-app-build
path: build/
5. Including Multiple Files
Example: Uploading multiple files with wildcard
name: Upload Artifacts
on: [push]
jobs:
upload:
runs-on: ubuntu-latest
steps:
- name: Upload logs
uses: actions/upload-artifact@v4
with:
name: build-logs
path: |
logs/*.log
reports/*.html
| Property | Description | Values |
|---|---|---|
| name | Unique name for the artifact | build-logs |
| path | File or directory pattern to upload | logs/*.log |
Note: The
path supports glob patterns and can include multiple files or directories.6. Excluding Files
| Option | Values | Description |
|---|---|---|
| exclude | string[] |
Array of file patterns to exclude from the artifact |
Example: Using exclude to filter files
name: Upload Artifact
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Upload artifact with exclusions
uses: actions/upload-artifact@v4
with:
name: my-artifact
path: |
build/
!build/*.log
!build/temp/
7. Downloading Specific Artifacts
| Property | Description | Example |
|---|---|---|
| github.event.artifacts | List of artifacts available for the current workflow run | github.event.artifacts |
| github.event.inputs.artifact-name | Name of the artifact to download (from workflow inputs) | github.event.inputs.artifact-name |
Example: Downloading Artifact by Name
name: Download Artifact
on:
workflow_dispatch:
inputs:
artifact-name:
description: 'Name of the artifact to download'
required: true
type: string
jobs:
download-artifact:
runs-on: ubuntu-latest
steps:
- name: Download Artifact
uses: actions/download-artifact@v4
with:
name: ${{ github.event.inputs.artifact-name }}
Note: The
actions/download-artifact action must be used with the name input to specify which artifact to download.
Warning: Ensure that the artifact name matches exactly, including case sensitivity.
8. Using Artifacts Between Jobs
| Property | Description | Values | Notes |
|---|---|---|---|
| jobs.<job_id>.outputs | Defines outputs for a job | {} |
Used to pass data between jobs |
| jobs.<job_id>.steps | Steps in a job | [] |
Can include id for referencing |
| steps.<step_id>.outputs | Defines outputs for a step | {} |
Used to pass data from a step to another job |
Example: Using Artifacts Between Jobs
name: Artifact Example
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Build Artifact
run: |
echo "Hello World" > artifact.txt
- name: Upload Artifact
uses: actions/upload-artifact@v4
with:
name: build-artifact
path: artifact.txt
deploy:
needs: build
runs-on: ubuntu-latest
steps:
- name: Download Artifact
uses: actions/download-artifact@v4
with:
name: build-artifact
path: ./downloaded
- name: Use Artifact
run: cat ./downloaded/artifact.txt
Note: The
needs keyword ensures that the deploy job runs only after the build job completes successfully.
9. Downloading Artifacts from UI
| Artifact | Download Option | Notes |
|---|---|---|
| Workflow Run | GitHub UI |
Access artifacts via the GitHub Actions interface |
| Artifact Name | artifact-name.zip |
Name of the artifact uploaded in the workflow |
Example: Downloading Artifact via GitHub UI
1. Navigate to the GitHub repository
2. Go to the "Actions" tab
3. Select the workflow run
4. Click on "Artifacts" in the sidebar
5. Click the download button for the desired artifactNote: Artifacts are retained for 90 days by default.
10. Using Artifacts with Matrix
| Property | Description | Values |
|---|---|---|
| strategy.matrix | Defines the matrix of build configurations | { os: ['ubuntu-latest', 'windows-latest'], node-version: ['14', '16'] } |
| artifacts.path | Path to the artifact files to upload | ./dist/** |
| artifacts.name | Name of the artifact (optional) | artifact-${{ matrix.os }}-${{ matrix.node-version }} |
Example: Matrix Artifact Upload
jobs:
build:
strategy:
matrix:
os: [ubuntu-latest, windows-latest]
node-version: [14, 16]
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
- run: npm ci
- run: npm run build
- name: Upload Artifact
uses: actions/upload-artifact@v3
with:
name: artifact-${{ matrix.os }}-${{ matrix.node-version }}
path: ./dist/**
Note: Artifacts are uploaded per job, so each matrix job will upload its own artifact.
11. Compressing Artifacts
| Option | Values | Notes |
|---|---|---|
| archive | zip, tar |
Compression format for artifacts |
| compression-level | 0 to 9 |
Level of compression (0 = no compression, 9 = maximum) |
Example: Compressing Artifacts with ZIP
name: Compress Artifacts
on:
workflow_run:
workflows: ["Build"]
jobs:
compress:
runs-on: ubuntu-latest
steps:
- name: Compress Artifact
uses: actions/upload-artifact@v4
with:
name: build-artifacts
path: build/
archive: zip
compression-level: 7
Note: The
upload-artifact action supports both zip and tar formats. Compression levels are only effective for zip format.
12. Managing Artifact Storage
| Property | Description | Default Value | Notes |
|---|---|---|---|
| actions/upload-artifact | Uploads artifact to GitHub Actions storage | N/A | Required for storing workflow artifacts |
| actions/download-artifact | Downloads artifact from GitHub Actions storage | N/A | Required for retrieving artifacts |
Example: Upload Artifact
name: Upload Artifact
on:
push:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Upload Artifact
uses: actions/upload-artifact@v4
with:
name: build-artifacts
path: build/
Example: Download Artifact
name: Download Artifact
on:
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Download Artifact
uses: actions/download-artifact@v4
with:
name: build-artifacts
path: build/
Note: Artifacts are stored for 90 days by default. You can configure retention policies in the repository settings.
Warning: Large artifacts can increase workflow run time and cost. Consider using
actions/upload-artifact@v4 with retention-days to manage storage.
| Property | Values | Description | Notes |
|---|---|---|---|
| retention-days | 1-90 |
Number of days to retain artifact | Default is 90 days |
| if-no-files-found | error, warn, ignore |
Action to take if no files are found | Default is error |
13. Deleting Artifacts
| Property | Description | Values |
|---|---|---|
| github.event.artifact.name | Name of the artifact to delete | string |
| github.event.artifact.id | ID of the artifact to delete | number |
Example: Delete Artifact by ID
name: Delete Artifact
on:
workflow_dispatch:
inputs:
artifact-id:
description: 'ID of the artifact to delete'
required: true
type: number
jobs:
delete-artifact:
runs-on: ubuntu-latest
steps:
- name: Delete Artifact
run: |
gh api \
--method DELETE \
"/repos/{owner}/{repo}/actions/artifacts/${{ github.event.inputs.artifact-id }}" \
-H "Accept: application/vnd.github.v3+json"
Note: Requires
gh CLI and appropriate permissions to delete artifacts.
Warning: Deleting an artifact is irreversible. Ensure you have backups or are certain about deletion before proceeding.