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 a command step 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:

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 pkg/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.