Variables and secrets

Reference variables in your pipeline

Variables are configured as environment variables in the build container. You can access the variables from the bitbucket-pipelines.yml file or any script that you invoke by referring to them in the following way: 

1 $AWS_SECRET

where AWS_SECRET is the name of the variable.

Default variables

Pipelines provides a set of default variables that are available for builds, and can be used in scripts.

You can override the default variables by specifying a variable with the same name.

Default variable

Description

CI

Default value is true. Gets set whenever a pipeline runs.

BITBUCKET_BUILD_NUMBER

The unique identifier for a build. It increments with each build and can be used to create unique artifact names.

BITBUCKET_CLONE_DIR

The absolute path of the directory that the repository is cloned into within the Docker container.

BITBUCKET_COMMIT

The commit hash of a commit that kicked off the build.

BITBUCKET_WORKSPACE

The name of the workspace in which the repository lives.

BITBUCKET_REPO_SLUG

The URL-friendly version of a repository name. For more information, see What is a slug?.

BITBUCKET_REPO_UUID

The UUID of the repository.

BITBUCKET_REPO_FULL_NAME

The full name of the repository (everything that comes after http://bitbucket.org/).

BITBUCKET_BRANCH

The source branch. This value is only available on branches.

Not available for builds against tags.

BITBUCKET_TAG

The tag of a commit that kicked off the build. This value is only available on tags.

Not available for builds against branches.

BITBUCKET_BOOKMARK

For use with Mercurial projects.

BITBUCKET_PARALLEL_STEP

Zero-based index of the current step in the group, for example: 0, 1, 2, …

Not available outside a parallel step.

BITBUCKET_PARALLEL_STEP_COUNT

Total number of steps in the group, for example: 5.

Not available outside a parallel step.

BITBUCKET_PR_ID

The pull request ID
Only available on a pull request triggered build.

BITBUCKET_PR_DESTINATION_BRANCH

The pull request destination branch (used in combination with BITBUCKET_BRANCH).

Only available on a pull request triggered build.

BITBUCKET_GIT_HTTP_ORIGIN

The URL for the origin, for example: http://bitbucket.org/<workspace>/<repo>

BITBUCKET_GIT_SSH_ORIGIN

Your SSH origin, for example: git@bitbucket.org:/<workspace>/<repo>.git

BITBUCKET_EXIT_CODE

The exit code of a step, can be used in after-script sections. Values can be 0 (success) or 1 (failed)

BITBUCKET_STEP_UUID

The UUID of the step.

BITBUCKET_PIPELINE_UUID

 The UUID of the pipeline.

BITBUCKET_DEPLOYMENT_ENVIRONMENT

The URL friendly version of the environment name.

BITBUCKET_DEPLOYMENT_ENVIRONMENT_UUID

The UUID of the environment to access environments via the REST API.

BITBUCKET_PROJECT_KEY

The key of the project the current pipeline belongs to.

BITBUCKET_PROJECT_UUID

The UUID of the project the current pipeline belongs to.

BITBUCKET_STEP_TRIGGERER_UUID

The person who kicked off the build ( by doing a push, merge etc), and for scheduled builds, the uuid of the pipelines user.

BITBUCKET_STEP_OIDC_TOKEN

The 'ID Token' generated by the Bitbucket OIDC provider that identifies the step. This token can be used to access resource servers, such as AWS and GCP without using credentials. Learn more

BITBUCKET_SSH_KEY_FILE

The location of the Bitbucket Pipelines private SSH key. This key can be used with BuildKit to access external resources using SSH.

This variable is only available for pipelines running on Bitbucket Cloud and the Linux Docker Pipelines runner.

 

User-defined variables

You can add, edit, or remove variables at the workspace, repository, and deployment environment levels. If you use the same name as an existing variable, you can override it. The order of overrides is Deployment > Repository > Workspace > Default variables. Each deployment environment is independent so you can use the same variable name with different values for each environment.

Before you begin bear in mind that:

  • Names can only contain ASCII letters, digits and underscores

  • Names are case-sensitive

  • Names can't start with a digit

  • Variables defined by the shell should not be used. You can find them by using a step with the command printenv.

Do not configure a pipeline variable with the name PATH or you might break all the pipeline steps. This happens because the shell uses PATH to find commands, so if you replace its usual list of locations then commands like docker won't work any more.

Workspace variables

Variables specified for a workspace can be accessed from all repositories that belong to the workspace. You must be an administrator to manage workspace variables.

  1. From your profile. avatar, select a workspace.

  2. Select the Settings cog on the top navigation bar.

  3. Select Workspace settings from the Settings dropdown menu.

  4. In the menu on the left, go to  Pipelines > Workspace variables.

  • Workspaces variables can be overridden by repository variables.

  • Workspace variables can be accessed by all users with the write permission for any repository (private or public) that belongs to the team or account.

  • You must be an administrator of a workspace or a repository to manage variables respectively.

Repository variables

Pipelines variables added at the repository level can be used by any user who has write access in the repository. To access and configure the repository variables, the user must be an admin of that repository.

From the repository, you can manage repository variables in Repository settings > Pipelines > Repository variablesNote: Repository variables override team variables.

Deployment variables

You can also define variables so that they can only be used in a specific deployment environment.

From the repository, you can manage deployment variables in Repository settings > Pipelines > Deployments. Note: Deployment variables override both team and repository variables, and are unique to each environment.

 

1 2 3 4 5 6 7 8 9 10 11 12 13 # Deployment variables will only work within deployment steps in bitbucket-pipelines.yaml image: atlassian/default-image:2 pipelines: default: - step: script: - <script> - step: name: Deploy to Test deployment: Test script: - echo $DEPLOYMENT_VARIABLE

Secured variables

You can secure a variable, which means it can be used in your scripts but its value will be hidden in the build logs (see example below). If you want to edit a secure variable, you can only give it a new value or delete it.  Secure variables are stored as encrypted values. Click the padlock to secure the variable.

padlock highlighted between value and add

Secured variable masking

Pipelines masks secure variables so they are not disclosed to your team members viewing build logs. If a value matching a secured variable appears in the logs, Pipelines will replace it with $VARIABLE_NAME.

This can lead to confusion about whether secured variables are working properly, so here's an example of how it works:

First, we have created a secure variable, MY_HIDDEN_NUMBER, with a value of 5.

secured variable example

Then we used this variable in the YAML file:

 

1 2 3 4 5 6 pipelines: default: - step: script: - expr 10 / $MY_HIDDEN_NUMBER - echo $MY_HIDDEN_NUMBER

The value of the variable can be used by the script, but will not be revealed in the logs. It is replaced with the name of the variable, $MY_HIDDEN_NUMBER.

example of a build log

Pipelines masks all occurrences of a secure variable's value in your log files, regardless of how that output was generated.

If you have secure variable value set to a common word, that word will be replaced with the variable name anywhere it appears in the log file. Secured variables are designed to be used for unique authentication tokens and passwords and so are unlikely to be also used in clear text.

Pipelines also matches some basic encodings of the variable value, like URL encoding, to prevent variables being displayed when used in URLs.

Third-party secret providers

This functionality is currently only available for pipelines using self-hosted runners.

If your organization uses a third-party secret management tool such as Hashicorp Vault to store or cycle secrets, Bitbucket Pipelines can integrate with that tool to retrieve secrets from that tool as needed.

This is an advanced feature which requires you to code middleware specific to your third-party secret provider.

To use a third-party secret provider:

  1. Code middleware to let your third-party secret provider communicate with Bitbucket.

  2. Set up your Bitbucket runner to contact your third-party secret provider.

  3. Set up your Bitbucket pipeline to retrieve secrets

1. Code middleware

We’ve provided a sample repository to get you started. This repository contains an example java app for a third-party secret provider integration.

This app:

  • Allows the provider to respond to secret requests from Bitbucket,

  • Validate the request is coming from Bitbucket using an OIDC JWT token.

  • Return a basic set of secrets.

Use this example as a starting point to code your own middleware specific to your third-party provider.

As you code your middleware, make sure to:

  • Use the Open API spec we’ve provided in the sample repository to ensure your middleware can communicate with Bitbucket.

  • Specify which secrets you want your third-party provider integration to send to Bitbucket. For an example of how to filter secrets, see the file SecretStoreImpl.java in our sample repository.

2. Set up your Bitbucket runner

To retrieve secrets from your third-party provider, you’ll need to:

  1. Set up your pipeline’s self-hosted runner to connect to your middleware.

  2. Specify which secrets you’d like to retrieve from your provider.

Set up your pipeline’s self-hosted runner

Your self-hosted runner needs to connect to your third-party secret provider at startup. To do this, you’ll need to provide the URI of the middleware you’ve written for your provider. Here’s how to do this for various kinds of self-hosted runner:

Docker

Set SECRET_PROVIDER_URI environment variable when starting the container:

1 docker container run ... -e SECRET_PROVIDER_URI="http://secret.provider/endpoint" ...
Shell

Add --secretProviderUri property when calling start.sh script:

1 ./start.sh ... --secretProviderUri "http://secret.provider/endpoint" ...
Powershell

Add -secretProviderUri property when calling start.ps1 script:

1 .\start ... -secretProviderUri "http://secret.provider/endpoint" ..

3. Set up your Bitbucket pipeline

To retrieve a secret from your third-party secret provider:

Your pipeline will automatically replace the current value of that variable with the secret hosted on your provider.

Make sure you’ve provisioned any secrets you’d like to retrieve when filtering what data your middleware can send to Bitbucket.

For example, if your pipeline contains a variable called $SECRET with a value of 1234 and your third-party secret provider contains a corresponding secret with the same name, your pipeline will replace 1234 with the appropriate secret value at runtime.

    Still need help?

    The Atlassian Community is here for you.