Learn · Secrets and agent security

Where secrets live

The recommended approach is that secrets do not live in Buildkite at all. They live in a dedicated secrets service — AWS Secrets Manager, GCP Secrets, HashiCorp Vault — and a job fetches what it needs, when it needs it. Buildkite publishes plugins for the common services, and they work with both self-hosted and Buildkite-hosted agents.

The reasoning is ownership. A secrets service already solves rotation, access audit, and revocation. Copying a credential out of it into a CI system means maintaining a second, worse copy of all three.

The agent environment hook

Where a dedicated service is not available, agents support an environment hook: a shell script sourced at the start of every job, which can export variables into the job’s environment.

The important part is the word every. An unconditional hook hands the credential to every job on that agent, including one opened by a pull request from a fork.

Scope it:

#!/bin/bash
set -euo pipefail

if [[ "$BUILDKITE_PIPELINE_SLUG" == "payments" && "$BUILDKITE_STEP_KEY" == "deploy" ]]; then
  export DEPLOYMENT_TOKEN="$(vault kv get -field=token secret/payments/deploy)"
fi

Checking both the pipeline and the step is the recommended pattern. It means a new step added to that pipeline does not silently inherit deployment credentials.

Why not the pipeline file

A secret in pipeline.yml is a secret in your git history, readable by everyone with repository access, present in every fork and every clone, and durable after rotation because git does not forget.

This is not a policy preference. It is the observation that the file is not a private place, and no amount of care about who can see the Buildkite UI changes that.

The queue boundary

Cluster and queue segmentation is a secrets control. Agents in a queue that serves production deploys can be configured with access that agents running pull-request builds simply do not have. The strongest version of “this job cannot reach that credential” is that the machine it runs on never had it.