Buildkite "Environment hook ... secret" failure in CI

By Daniel Zoghalchali·Latchkey

Buildkite agents load secrets in the environment hook before a step runs. If the hook cannot fetch or export a secret, the step starts with the variable unset and later fails on a missing credential.

What this error means

The environment hook logs a failure fetching a secret, or the step later fails because an expected env var (an API token, a password) is empty.

~/.buildkite-agent/hooks/environment: line 8: failed to read secret "DEPLOY_TOKEN"
Running command
Error: DEPLOY_TOKEN is not set

Common causes

The hook cannot reach the secret source

The environment hook calls a secret manager that the agent cannot authenticate to, so no value is exported.

The secret name is wrong

The hook requests a key that does not exist under the expected path, so nothing is loaded and the variable stays unset.

How to fix it

Fix hook auth and export the secret

1. Confirm the agent can authenticate to the secret source (IAM role, token) used by the environment hook.
2. Verify the secret key exists at the expected path.
3. Export it in the hook and fail the hook when it is missing.

#!/bin/bash
set -euo pipefail
DEPLOY_TOKEN="$(aws secretsmanager get-secret-value --secret-id deploy-token --query SecretString --output text)"
export DEPLOY_TOKEN

Fail fast on a missing secret

Have the hook exit non-zero when a required secret is empty so the step does not run half-configured.

: "${DEPLOY_TOKEN:?environment hook did not load DEPLOY_TOKEN}"

How to prevent it

• Give agents scoped access to the exact secrets their hooks read.
• Fail the environment hook when a required secret is missing.
• Keep secret names in one place to avoid drift.

Frequently asked questions

Related guides

References

• GitHub Actions documentation