What are repository variables in Bitbucket and how do you manage secrets?

Think of repository variables like a hotel room safe. You put your valuables (secrets) inside, lock it with a code, and only authorized guests (pipeline steps) can access the contents. The safe's contents are never displayed on the room's TV (build logs), even if someone tries to print them.

Repository variables in Bitbucket Pipelines allow you to store configuration values and secrets outside your codebase. When a pipeline runs, these variables are injected as environment variables into the Docker container. You create them in the Bitbucket UI under Repository Settings > Pipelines > Repository Variables. Each variable has a name, a value, and a 'Secured' checkbox. When a variable is marked as secured, its value is encrypted at rest, masked in build logs (replaced with asterisks), and cannot be viewed again in the UI after creation.

Variables follow a hierarchy with three levels of scope. Workspace variables are available to all repositories in the workspace, making them ideal for shared secrets like a Docker Hub password or an organization-wide API key. Repository variables are scoped to a single repository. Deployment variables are tied to a specific deployment environment (like staging or production) and are only injected when a step targets that environment. If the same variable name exists at multiple levels, the most specific scope wins: deployment overrides repository, which overrides workspace.

In production, teams typically store database connection strings, API keys, cloud provider credentials, and Docker registry passwords as secured repository variables. The deployment-level scoping is particularly useful: you can have a DATABASE_URL variable with different values for staging and production, and the correct value is automatically injected based on the deployment target in the pipeline step. This prevents accidental production deployments with staging credentials.

A critical gotcha: secured variables are not available in pipelines triggered by forks. This is a security feature to prevent a malicious fork from exfiltrating your secrets. If your open-source project relies on secured variables for testing, fork-triggered pipelines will fail. Additionally, while secured variables are masked in logs, a determined attacker could encode the value (e.g., base64) to bypass masking. Never rely solely on log masking as a security measure; limit who can modify pipeline configurations.