upload-artifact
A GitHub Action for uploading files and directories as workflow artifacts, enabling data sharing between jobs and runs.
What is upload-artifact?
`@actions/upload-artifact` is an official GitHub Action that uploads files and directories generated during a workflow run as persistent artifacts. It solves the problem of sharing data between jobs or preserving build outputs, logs, or test results for later analysis. The action integrates seamlessly into GitHub Actions workflows, providing configurable options for path selection, compression, and artifact lifecycle management.
Developers and DevOps engineers using GitHub Actions for CI/CD who need to pass build artifacts, test results, or other files between jobs or retain them post-workflow. It's essential for teams building, testing, and deploying software with GitHub's automation platform.
Developers choose this action because it's the official, maintained solution for artifact uploads on GitHub Actions, offering high performance, reliability, and deep integration with the platform. Its immutable artifact design prevents data corruption, and features like compression tuning and wildcard support provide flexibility not always found in custom scripts.
Overview
@actions/upload-artifact is an official GitHub Action that allows developers to upload files, directories, or files matching wildcard patterns as artifacts from their workflow runs. These artifacts are stored by GitHub and can be downloaded later or used by other jobs in the same workflow, facilitating data persistence and sharing across CI/CD steps.
Key Features
- Flexible Path Specification — Upload individual files, entire directories, or use wildcard patterns and exclusions to select specific files.
- Performance and Control — Manually adjust compression levels for speed or size, and customize behavior when no files are found.
- Artifact Management — Set custom retention periods, overwrite existing artifacts, and include or exclude hidden files from uploads.
- Output Integration — Provides artifact IDs, URLs, and digests as outputs for use in subsequent steps or with the GitHub REST API.
- Immutable Archives — Each upload creates a unique, immutable artifact, preventing accidental corruption from concurrent modifications.
Philosophy
The action is designed to be a reliable, performant, and secure method for persisting workflow data, with sensible defaults that prioritize safety (like excluding hidden files) while offering granular control for advanced use cases.
Use Cases
Best For
- Sharing build outputs (like binaries or packages) between jobs in a GitHub Actions workflow.
- Persisting test results or coverage reports for later review or integration with external tools.
- Uploading logs or diagnostic files generated during CI/CD runs for debugging purposes.
- Passing configuration files or data between sequential jobs in a workflow matrix.
- Archiving generated documentation or static assets after a build process.
- Storing performance profiling data or benchmarks from automated tests.
Not Ideal For
- Workflows requiring appending files to the same artifact across multiple parallel jobs, as v4 prohibits duplicate artifact names per run.
- Projects needing exact file permission preservation or non-Zip archive formats, due to inherent limitations in the upload process.
- Teams on GitHub Enterprise Server (GHES) requiring the latest performance features, since v4+ is unsupported on GHES.
- High-volume CI pipelines that might exceed the 500 artifact limit per job, necessitating alternative storage solutions.
Pros & Cons
Pros
v4 offers up to 90% faster upload speeds and creates immutable archives, preventing data corruption from concurrent modifications, as highlighted in the 'Improvements' section.
Supports wildcards, exclusions, and multiple paths for precise file selection without manual scripting, demonstrated in examples like 'Upload using Multiple Paths and Exclusions'.
Allows compression level adjustment from 0 to 9, optimizing for speed or size based on file types, with specific guidance for large binaries in the 'Altering compression level' example.
Provides artifact IDs, URLs, and digests as outputs for automation with the GitHub REST API and inter-job data passing, detailed in the 'Outputs' and 'Using Outputs' sections.
Cons
v4 removed the ability to upload to the same artifact from multiple jobs, breaking previous workflows and requiring careful artifact naming in matrices, as warned in the 'Breaking Changes'.
Latest versions (v4+) are not supported on GitHub Enterprise Server, forcing users to stick with older, deprecated versions, noted in the 'v4 - What's new' section.
File permissions are lost during upload, and artifacts are always Zip files with no alternative formats, limiting use cases for executables or direct access, as stated in 'Limitations'.
Frequently Asked Questions
Related Projects
checkoutAction for checking out a repo
cacheCache dependencies and build outputs in GitHub Actions
github-scriptWrite workflows scripting the GitHub API in JavaScript
download-artifactThe `@actions/download-artifact` action enables GitHub Actions workflows to retrieve stored artifacts from workflow runs. It provides flexible options for downloading single or multiple artifacts, filtering by patterns, and accessing artifacts across different repositories and runs. ## Key Features - **Single Artifact Download** — Download a specific artifact by name or unique ID to a specified directory. - **Bulk Artifact Retrieval** — Download all artifacts from a run, with options to merge them into a single directory or keep them separate. - **Cross-Repository Access** — Download artifacts from other repositories or workflow runs using a GitHub token with appropriate permissions. - **Pattern Filtering** — Use glob patterns to download only matching artifacts, useful in multi-architecture build scenarios. - **Flexible Output Control** — Choose whether to automatically decompress artifacts or maintain them as-is for manual handling. - **File Permission Preservation** — Supports workflows that require maintaining executable permissions via tar archives. ## Philosophy The action is designed to be a reliable, configurable tool for artifact retrieval within GitHub's ecosystem, prioritizing compatibility with the platform's artifact system and providing clear, predictable behavior for common use cases.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.