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 in Build Steps

Upload artifacts in your build steps by defining file path patterns, either in artifact_paths attribute of your command step or in the “Automatic Artifact Uploading” field of the Buildkite UI.

The following example shows the Buildkite UI configured to upload any artifacts in the logs or coverage directories, as well as any of their subdirectories. Files will be uploaded automatically to logs/ or coverage/ respectively.

Artifact pattern configuration

And the same configuration in YAML:

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

Uploading Artifacts from Scripts

Upload artifacts from your build scripts with the buildkite-agent artifact command. The following example uploads build.tar.gz from the pkg directory to pgk/build.tar.gz:

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

For full documentation of the buildkite-agent artifact upload command see the buildkite-agent artifact upload documentation.

Downloading Artifacts

You can download artifacts created by a build job, from inside a running build, using the buildkite-agent artifact download command. For example, to download all artifacts in the logs directory (including subdirectories, which will be recreated) to local-logs/logs/:

buildkite-agent artifact download logs/* local-logs/

The buildkite-agent artifact command will find the most recent file uploaded with a 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, to download a build.zip artifact you uploaded in the "build" pipeline step:

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

To download artifacts from triggered builds, pass the $BUILDKITE_TRIGGERED_FROM_BUILD_ID environment variable to the download command:

buildkite-agent artifact download "*.jpg" images/ --build $BUILDKITE_TRIGGERED_FROM_BUILD_ID

For full documentation of the buildkite-agent artifact download command 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.