Using Build Artifacts

In this guide we’ll walk through using the Buildkite Agent’s artifact support to store and retrieve files between different steps in a build pipeline.

Uploading Artifacts

To automatically upload artifacts created by a build step, set the artifact-paths attribute on your command step. In this example, any artifacts that are created in the logs or coverage directories, as well as any of their subdirectories, will be uploaded automatically:

steps:
  - label: "🔨 Tests"
    command:
      - "npm install"
      - "tests.sh"
    artifact_paths:
      - "logs/**/*"
      - "coverage/**/*"

If you've defined your pipeline in Buildkite, you can set this field on a command step using the “Automatic Artifact Uploading” option:

Artifact pattern configuration

Defining a pattern here will cause your agents to automatically upload any artifacts that match your file path pattern.

You can also perform an artifact upload manually in your build scripts by using the buildkite-agent artifact command. In this example, the file build.tar.gz from the pkg directory will be uploaded to the default destination:

buildkite-agent artifact upload pkg/build.tar.gz

You can then download the artifact in subsequent build steps (even if the build step is running on a different build server).

For full documentation of the buildkite-agent artifact upload command, and examples of supported glob patterns, see the buildkite-agent artifact upload documentation.

Downloading Artifacts

You can download artifacts created by a build job using the buildkite-agent artifact download command. For example:

buildkite-agent artifact download pkg/build.tar.gz pkg/

If an artifact was previously uploaded at pkg/build.tar.gz, the above command will download it to the pkg directory.

The buildkite-agent artifact command will find the last file uploaded with the matching filename, no matter which build step uploaded it. If you want to target an artifact from a particular build step use the --step argument. For example:

buildkite-agent artifact download build.zip tmp/ --step build

This will download the build.zip file from the pipeline step with the label "build".

For full documentation and examples, see the buildkite-agent artifact download documentation.

Downloading Artifacts Outside a Running Build

The buildkite-agent artifact download command only works within the context of a running build.

If you want to download an artifact from outside a build use our Artifact Download API.

Further documentation

See the Buildkite Agent artifact documentation for a full list of options and details of Buildkite’s artifact support.