toolkit/packages/artifact

@actions/artifact

Usage

You can use this package to interact with the actions artifacts.

• Upload an Artifact
• Download a Single Artifact
• Download All Artifacts
• Additional Documentation
• Contributions

Relative paths and absolute paths are both allowed. Relative paths are rooted against the current working directory.

Upload an Artifact

Method Name: uploadArtifact

Inputs

• name
  • The name of the artifact that is being uploaded
  • Required
• files
  • A list of file paths that describe what should be uploaded as part of the artifact
  • If a path is provided that does not exist, an error will be thrown
  • Can be absolute or relative. Internally everything is normalized and resolved
  • Required
• rootDirectory
  • A file path that denotes the root directory of the files being uploaded. This path is used to strip the paths provided in files to control how they are uploaded and structured
  • If a file specified in files is not in the rootDirectory, an error will be thrown
  • Required
• options
  • Extra options that allow for the customization of the upload behavior
  • Optional

Available Options

• continueOnError
  • Indicates if the artifact upload should continue in the event a file fails to upload. If there is a error during upload, a partial artifact will always be created and available for download at the end. The size reported will be the amount of storage that the user or org will be charged for the partial artifact.
  • If set to false, and an error is encountered, all other uploads will stop and any files that were queued will not be attempted to be uploaded. The partial artifact available will only include files up until the failure.
  • If set to true and an error is encountered, the failed file will be skipped and ignored and all other queued files will be attempted to be uploaded. There will be an artifact available for download at the end with everything excluding the file that failed to upload
  • Optional, defaults to true if not specified
• retentionDays
  • Duration after which artifact will expire in days
  • Minimum value: 1
  • Maximum value: 90 unless changed by repository setting
  • If this is set to a greater value than the retention settings allowed, the retention on artifacts will be reduced to match the max value allowed on the server, and the upload process will continue. An input of 0 assumes default retention value.

Example using Absolute File Paths

const artifact = require('@actions/artifact');
const artifactClient = artifact.create()
const artifactName = 'my-artifact';
const files = [
    '/home/user/files/plz-upload/file1.txt',
    '/home/user/files/plz-upload/file2.txt',
    '/home/user/files/plz-upload/dir/file3.txt'
]
const rootDirectory = '/home/user/files/plz-upload'
const options = {
    continueOnError: true
}

const uploadResult = await artifactClient.uploadArtifact(artifactName, files, rootDirectory, options)

Example using Relative File Paths

// Assuming the current working directory is /home/user/files/plz-upload
const artifact = require('@actions/artifact');
const artifactClient = artifact.create()
const artifactName = 'my-artifact';
const files = [
    'file1.txt',
    'file2.txt',
    'dir/file3.txt'
]

const rootDirectory = '.' // Also possible to use __dirname
const options = {
    continueOnError: false
}

const uploadResponse = await artifactClient.uploadArtifact(artifactName, files, rootDirectory, options)

Upload Result

The returned UploadResponse will contain the following information

• artifactName
  • The name of the artifact that was uploaded
• artifactItems
  • A list of all files that describe what is uploaded if there are no errors encountered. Usually this will be equal to the inputted files with the exception of empty directories (will not be uploaded)
• size
  • Total size of the artifact that was uploaded in bytes
• failedItems
  • A list of items that were not uploaded successfully (this will include queued items that were not uploaded if continueOnError is set to false). This is a subset of artifactItems

Download a Single Artifact

Method Name: downloadArtifact

Inputs

• name
  • The name of the artifact to download
  • Required
• path
  • Path that denotes where the artifact will be downloaded to
  • Optional. Defaults to the GitHub workspace directory($GITHUB_WORKSPACE) if not specified
• options
  • Extra options that allow for the customization of the download behavior
  • Optional

Available Options

• createArtifactFolder
  • Specifies if a folder (the artifact name) is created for the artifact that is downloaded (contents downloaded into this folder),
  • Optional. Defaults to false if not specified

Example

const artifact = require('@actions/artifact');
const artifactClient = artifact.create()
const artifactName = 'my-artifact';
const path = 'some/directory'
const options = {
    createArtifactFolder: false
}

const downloadResponse = await artifactClient.downloadArtifact(artifactName, path, options)

// Post download, the directory structure will look like this
/some
    /directory
        /file1.txt
        /file2.txt
        /dir
            /file3.txt

// If createArtifactFolder is set to true, the directory structure will look like this
/some
    /directory
        /my-artifact
            /file1.txt
            /file2.txt
            /dir
                /file3.txt

Download Response

The returned DownloadResponse will contain the following information

• artifactName
  • The name of the artifact that was downloaded
• downloadPath
  • The full Path to where the artifact was downloaded

Download All Artifacts

Method Name: downloadAllArtifacts

Inputs

• path
  • Path that denotes where the artifact will be downloaded to
  • Optional. Defaults to the GitHub workspace directory($GITHUB_WORKSPACE) if not specified

const artifact = require('@actions/artifact');
const artifactClient = artifact.create();
const downloadResponse = await artifactClient.downloadAllArtifacts();

// output result
for (response in downloadResponse) {
    console.log(response.artifactName);
    console.log(response.downloadPath);
}

Because there are multiple artifacts, an extra directory (denoted by the name of the artifact) will be created for each artifact in the path. With 2 artifacts(my-artifact-1 and my-artifact-2 for example) and the default path, the directory structure will be as follows:

/GITHUB_WORKSPACE
    /my-artifact-1
        / .. contents of `my-artifact-1`
    /my-artifact-2
        / .. contents of `my-artifact-2`

Download Result

An array will be returned that describes the results for downloading all artifacts. The number of items in the array indicates the number of artifacts that were downloaded.

Each artifact will have the same DownloadResponse as if it was individually downloaded

• artifactName
  • The name of the artifact that was downloaded
• downloadPath
  • The full Path to where the artifact was downloaded

Additional Documentation

Check out additional-information for extra documentation around usage, restrictions and behavior.

Check out implementation-details for extra information about the implementation of this package.

Contributions

See contributor guidelines for general guidelines and information about toolkit contributions.

For contributions related to this package, see artifact contributions for more information.