actions
/
toolkit
mirror of https://github.com/actions/toolkit
1
0
Fork 0
Code
toolkit/packages/artifact/README.md

3.2 KiB
Raw Permalink Blame History

@actions/artifact

Usage

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

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

  • 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
  • size
    • Total size of the artifact that was uploaded in bytes

Contributions

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

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