@actions/artifact
Advanced tools
@actions/artifact is an npm package designed for use with GitHub Actions. It allows you to upload and download build artifacts, which can be useful for sharing data between jobs in a workflow or for persisting data after a workflow completes.
Upload Artifacts
This feature allows you to upload files as artifacts. The code sample demonstrates how to create an artifact client, specify the files to be uploaded, and then upload them.
const artifact = require('@actions/artifact');
const artifactClient = artifact.create();
const artifactName = 'my-artifact';
const files = ['path/to/file1', 'path/to/file2'];
const rootDirectory = 'path/to';
const options = { continueOnError: false };
artifactClient.uploadArtifact(artifactName, files, rootDirectory, options).then(response => {
console.log(`Artifact ${response.artifactName} has been successfully uploaded!`);
}).catch(error => {
console.error(`Failed to upload artifact: ${error}`);
});Download Artifacts
This feature allows you to download previously uploaded artifacts. The code sample demonstrates how to create an artifact client, specify the artifact to be downloaded, and then download it.
const artifact = require('@actions/artifact');
const artifactClient = artifact.create();
const artifactName = 'my-artifact';
const downloadPath = 'path/to/download';
artifactClient.downloadArtifact(artifactName, downloadPath).then(response => {
console.log(`Artifact ${response.artifactName} has been successfully downloaded to ${response.downloadPath}`);
}).catch(error => {
console.error(`Failed to download artifact: ${error}`);
});List Artifacts
This feature allows you to list all artifacts for a given workflow run. The code sample demonstrates how to create an artifact client and list all artifacts.
const artifact = require('@actions/artifact');
const artifactClient = artifact.create();
artifactClient.listArtifacts().then(response => {
console.log('Artifacts:', response.artifacts);
}).catch(error => {
console.error(`Failed to list artifacts: ${error}`);
});The azure-storage package provides similar functionality for uploading and downloading files, but it is designed for use with Azure Blob Storage. Unlike @actions/artifact, which is specifically tailored for GitHub Actions, azure-storage is more general-purpose and can be used in a variety of contexts.
The aws-sdk package offers comprehensive functionality for interacting with AWS services, including S3 for file storage. It provides similar capabilities for uploading and downloading files, but it is more complex and versatile, supporting a wide range of AWS services beyond just artifact management.
@actions/artifactInteract programmatically with Actions Artifacts.
This is the core library that powers the @actions/upload-artifact and @actions/download-artifact actions.
[!IMPORTANT] @actions/artifact v2+, upload-artifact@v4+, and download-artifact@v4+ are not currently supported on GHES yet. The previous version of this package can be found at this tag and on npm.
The release of @actions/artifact@v2 (including upload-artifact@v4 and download-artifact@v4) are major changes to the backend architecture of Artifacts. They have numerous performance and behavioral improvements.
actions/download-artifact) now support downloading Artifacts from other repositories and runs if a GITHUB_TOKEN with sufficient actions:read permissions are provided.Firewall rules required for self-hosted runners.
If you are using self-hosted runners behind a firewall, you must have flows open to Actions endpoints. If you cannot use wildcard rules for your firewall, see the GitHub meta endpoint for specific endpoints.
e.g.
curl https://api.github.com/meta | jq .domains.actions
Uploading to the same named Artifact multiple times.
Due to how Artifacts are created in this new version, it is no longer possible to upload to the same named Artifact multiple times. You must either split the uploads into multiple Artifacts with different names, or only upload once.
Limit of Artifacts for an individual job.
Each job in a workflow run now has a limit of 10 artifacts.
Install the package:
npm i @actions/artifact
Import the module:
// ES6 module
import {DefaultArtifactClient} from '@actions/artifact'
// CommonJS
const {DefaultArtifactClient} = require('@actions/artifact')
Then instantiate:
const artifact = new DefaultArtifactClient()
ℹ️ For a comprehensive list of classes, interfaces, functions and more, see the generated documentation.
The most basic scenario is uploading one or more files to an Artifact, then downloading that Artifact. Downloads are based on the Artifact ID, which can be obtained in the response of uploadArtifact, getArtifact, listArtifacts or via the REST API.
const {id, size} = await artifact.uploadArtifact(
// name of the artifact
'my-artifact',
// files to include (supports absolute and relative paths)
['/absolute/path/file1.txt', './relative/file2.txt'],
{
// optional: how long to retain the artifact
// if unspecified, defaults to repository/org retention settings (the limit of this value)
retentionDays: 10
}
)
console.log(`Created artifact with id: ${id} (bytes: ${size}`)
const {downloadPath} = await artifact.downloadArtifact(id, {
// optional: download destination path. otherwise defaults to $GITHUB_WORKSPACE
path: '/tmp/dst/path',
})
console.log(`Downloaded artifact ${id} to: ${downloadPath}`)
To delete an artifact, all you need is the name.
const {id} = await artifact.deleteArtifact(
// name of the artifact
'my-artifact'
)
console.log(`Deleted Artifact ID '${id}'`)
It also supports options to delete from other repos/runs given a github token with actions:write permissions on the target repository is supplied.
const findBy = {
// must have actions:write permission on target repository
token: process.env['GITHUB_TOKEN'],
workflowRunId: 123,
repositoryOwner: 'actions',
repositoryName: 'toolkit'
}
const {id} = await artifact.deleteArtifact(
// name of the artifact
'my-artifact',
// options to find by other repo/owner
{ findBy }
)
console.log(`Deleted Artifact ID '${id}' from ${findBy.repositoryOwner}/ ${findBy.repositoryName}`)
It may be useful to download Artifacts from other workflow runs, or even other repositories. By default, the permissions are scoped so they can only download Artifacts within the current workflow run. To elevate permissions for this scenario, you must specify options.findBy to downloadArtifact.
const findBy = {
// must have actions:read permission on target repository
token: process.env['GITHUB_TOKEN'],
workflowRunId: 123,
repositoryOwner: 'actions',
repositoryName: 'toolkit'
}
await artifact.downloadArtifact(1337, {
findBy
})
// can also be used in other methods
await artifact.getArtifact('my-artifact', {
findBy
})
await artifact.listArtifacts({
findBy
})
If you have large files that need to be uploaded (or file types that don't compress well), you may benefit from changing the compression level of the Artifact archive. NOTE: This is a tradeoff between artifact upload time and stored data size.
await artifact.uploadArtifact('my-massive-artifact', ['big_file.bin'], {
// The level of compression for Zlib to be applied to the artifact archive.
// - 0: No compression
// - 1: Best speed
// - 6: Default compression (same as GNU Gzip)
// - 9: Best compression
compressionLevel: 0
})
FAQs
Actions artifact lib
The npm package @actions/artifact receives a total of 182,118 weekly downloads. As such, @actions/artifact popularity was classified as popular.
We found that @actions/artifact demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
pnpm's new minimumReleaseAge setting delays package updates to prevent supply chain attacks, with other tools like Taze and NCU following suit.
Security News
The Rust Security Response WG is warning of phishing emails from rustfoundation.dev targeting crates.io users.
Product
Socket now lets you customize pull request alert headers, helping security teams share clear guidance right in PRs to speed reviews and reduce back-and-forth.