Buildkite's own guidance is to keep pipeline secrets in a secrets service you control, such as AWS Secrets Manager or HashiCorp Vault, and fetch them at job time. Buildkite secrets and agent environment hooks are the other options. Scope each secret to one pipeline and step, and rotate anything that shows up in a log.
What are the options?
Buildkite describes a hybrid model: the control plane schedules work, and agents run in your infrastructure or as hosted agents. That shapes where a secret should sit.
- Your own secrets store. Buildkite's page calls this the best practice. Plugins exist for AWS, Google Cloud with workload identity federation, and Vault. The aim is that secrets stay in your infrastructure and are never stored in, or sent to, Buildkite.
- Environment hooks on self-hosted agents. A shell script in the agent hooks directory is sourced at the start of each job and can export secrets. It works without a store, but the secret lives on the agent host.
- Buildkite secrets. Values are stored encrypted at rest and in transit, scoped to a cluster, and decrypted by the Buildkite control plane before being sent to the agent. They work with hosted and self-hosted agents.
The trade is simple. Option 1 keeps the value out of Buildkite. Option 3 is easier to run, but the value does pass through the vendor.
How do you stop one job from reading another job's secret?
Buildkite's hook example checks the pipeline slug before it exports a token, and a stricter example also checks the step key. That condition is the point: an environment hook that exports a secret unconditionally gives it to every job on that agent, including a job from a pipeline that has nothing to do with it.
Constructed example: a shared agent pool runs a deploy pipeline and a docs pipeline. The hook exports the production deploy token with no condition. Someone adds a docs step that runs env for debugging. The token is now in a build log for a team that should never have seen it. Adding a slug and step check to the hook closes that route.
For Buildkite secrets the control is the agent access policy. Policies restrict which agents can read which secrets during builds, and each cluster has its own encryption key, so a secret in one cluster is not readable from another.
What does redaction do, and not do?
Buildkite redacts the value of any Buildkite secret that is printed to standard output, and says that if you ever see an unredacted value you should rotate it and contact their security team. Redaction is a safety net. The docs describe it for the secret value as stored, so a transformed copy, such as an encoded or split version, may not be caught. Treat a printed secret as leaked even when the log looks clean.
Practical limits worth knowing from the docs: keys may contain letters, numbers and underscores, cannot start with the prefixes buildkite or bk, and values are capped at 32 kilobytes. Once saved, the value is no longer visible in the interface, and the Secrets page shows a "Last read" column, which is useful for finding secrets nobody uses.
What to do
- Decide per secret: store you control, hook, or Buildkite secret. Write the decision down.
- Prefer short-lived credentials from workload identity over long-lived keys where a plugin exists.
- In environment hooks, export secrets only after checking pipeline slug and step key.
- Give production secrets their own cluster and agent access policy.
- Run deploy steps on agents that other pipelines cannot use.
- Sort the Secrets page by "Last read" and remove the ones never read.
- Treat any secret printed in a log as compromised and rotate it.
- Scan the repository for committed credentials so a hook is not the only line of defence.
Safeguard secrets scanning and policy gates can check repositories for committed credentials and block merges on a finding, which complements the controls above.
Quick check
Is a Buildkite secret ever sent to the agent in clear text?
Buildkite says secrets are decrypted by its control plane and then sent to the agent, protected in transit. The agent needs the plain value to use it, so limit which agents can reach it.
Can I rely on log redaction alone?
No. Redaction matches the secret value and is a backstop. Avoid printing secrets, and rotate any that appear.
Sources
- Managing pipeline secrets, Buildkite Docs, fetched 18 October 2026
- Buildkite secrets, Buildkite Docs, fetched 18 October 2026
Last reviewed: 18 October 2026.
