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. Artifacts can be uploaded to a Buildkite-managed storage location, where they're retained for six months, or your own artifact storage location on Amazon S3, Google Cloud Storage, or Artifactory. Presently, Buildkite-managed artifacts are stored on Amazon S3.

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:

  - label: "🔨 Tests"
      - "npm install"
      - ""
      - "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 artifact you uploaded in the "build" pipeline step:

buildkite-agent artifact download 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 of 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.

Encryption and security

Buildkite has zero access to your source code in the pipelines and only receives and stores the log output of the builds and build artifacts in encrypted form.

Logs are AES-encrypted, and the build artifacts are encrypted in transit and at rest using AWS encryption (KMS or S3 SSE). As a result, the keys cannot be extracted on the Buildkite's side, and the AWS solutions provide mitigations against zero-day attacks and other security issues. Beyond this, the control over security measures within your infrastructure is up to you.

If you choose to host your build artifacts yourself, they end up in your private AWS bucket.

If you are a Buildkite customer on the Enterprise plan, you can also set up a private AWS S3 build log archive location and store the logs in your private bucket.

To further tighten the security in a Buildkite organization, you can use the API Access Audit to track the actions of the users who have API Access Tokens that can access your organization's data using the REST and GraphQL API.

Further documentation

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