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 are uploaded to a Buildkite-managed Amazon S3 bucket, where they’re retained for six months, or you can specify an alternate destination on Amazon S3, Google Cloud Storage or Artifactory.

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.

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.

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

If you choose to host your own build artifacts, they never leave your infrastructure and end up in your private AWS bucket.

If you are a Buildkite Enterprise user, 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 via 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.