Variables in pipelines

Bitbucket Pipelines provides a set of default variables as well as the ability to define your own variables. You can mark variables as secured for additional security of your passwords, tokens, and other values. You can also update your variables when you run a pipeline manually.

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 adding $ in front such as:


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 variableDescription
CI Default value is true. Gets set whenever a pipeline runs.
BITBUCKET_BOOKMARKFor use with Mercurial projects.

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

Not available for builds against tags, or custom pipelines triggered from a commit.

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

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

BITBUCKET_COMMITThe commit hash of a commit that kicked off the build.
BITBUCKET_DEPLOYMENT_ENVIRONMENTThe name of the environment which the step deploys to. This is only available on deployment steps.

The UUID of the environment which the step deploys to. This is only available on deployment steps.

BITBUCKET_EXIT_CODEThe exit code of a step, can be used in after-script sections. Values can be 0 (success) or 1 (failed)
BITBUCKET_GIT_HTTP_ORIGINThe URL for the origin, for example:<account>/<repo>
BITBUCKET_GIT_SSH_ORIGINYour SSH origin, for example:<account>/<repo>.git

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

Not available outside a parallel step.


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

Not available outside a parallel step.


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

Only available on a pull request triggered build.

BITBUCKET_PR_IDThe pull request ID
Only available on a pull request triggered build.
BITBUCKET_PROJECT_KEYThe key of the project in which the repository lives.
BITBUCKET_PROJECT_UUIDThe UUID of the project in which the repository lives.
BITBUCKET_REPO_FULL_NAMEThe full name of the repository (everything that comes after
BITBUCKET_REPO_OWNERThe name of the account in which the repository lives.
BITBUCKET_REPO_OWNER_UUIDThe UUID of the account in which the repository lives.
BITBUCKET_REPO_SLUGThe URL-friendly version of a repository name. For more information, see What is a slug?.
BITBUCKET_REPO_UUIDThe UUID of the repository.
BITBUCKET_STEP_RUN_NUMBERNumber of times a step has been executed per pipeline.
BITBUCKET_STEP_TRIGGERER_UUIDUUID from the user who triggered the step execution.

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

Not available for builds against branches.

User-defined variables

You can add, edit, or remove variables at the account, 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 > Account > Default variables. Each deployment environment is independent so you can use the same variable name with different values for each environment.

  • Names can only contain ASCII letters, digits and underscores
  • Names are case-sensitive
  • Names can't start with a digit
  • Variables can't contain line breaks. If you need a variable containing a line break, then use the base64 or openssl command to encode your variable, and add the output to your variables. Then, within your bitbucket-pipelines.yml file, decode the variable to use it in your scripts.

Team and individual account variables


  • Team or individual account 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 an account or a repository to manage variables respectively. If you don't have the necessary level of permission, you will not see the menu option at all.
  • Variables specified for a team or an individual account can be accessed from all repositories that belong to the team or account. You must be an administrator to manage team variables.
  • Team or individual account variables can be overridden by repository variables.


To manage team or individual account variables:

  1. From your avatar in the bottom left, click Bitbucket settings.
  2. Select an individual account or a team for which you want to configure variables:
    Picture of settings dropdown
  3. In the menu on the left, under Pipelines, select Account variables.

Repository variables

Variables added at the repository level can be accessed by any user with the push permission in the repository. These variables override team variables.

You can manage repository variables in Settings > Pipelines > Repository variables

Deployment variables

You can define variables so that they can only be used in a specific deployment environment. Deployment variables override both team and repository variables, and are unique to each environment.


To manage deployment variables go to  Settings > Pipelines > Deployments.

You can also restrict deployment to certain branches or for admins only. If you do, only people with permission to deploy can use these deployment variables.

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.

image showing padlock to secure

Secured variable masking

Pipelines masks secure variables so they are not shown 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.

Then we used this bitbucket-pipelines.yml file:

    - step:
          - 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 logs using a secured variable

Note:  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.

Add variables for manual pipelines

Sometimes it's useful to add or update variables when you run a custom pipeline, for example to give a version number, or a single use value.


  • You will override any repository, or account, variable that has the same name.
  • If you don't enter a value, that variable will be empty (that is, it will have the value "").
  • The values are temporary (you cannot rerun the pipeline, and it won't permanently change existing variables).
  • These variables are not secured, and will show up in logs even if you override a previously secure variable.


To enable manual variable updates, define the variables under your custom pipeline that you want to enter at launch:

    custom-name-and-region: #name of this pipeline
      - variables:			#list variable names under here
          - name: Username
          - name: Region
      - step: 
            - echo "User name is $Username"
            - echo "and they are in $Region"

Then, when you run a custom pipeline (Branches > ⋯ > Run pipeline for a branch > Custom:..) you'll be able to fill them in.

picture of custom variable popup ready to fill in

Last modified on Jul 2, 2019

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.