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, or custom pipelines.

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/<account>/<repo>

BITBUCKET_GIT_SSH_ORIGIN

Your SSH origin, for example: git@bitbucket.org:/<account>/<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.

 

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.

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 avatar in the bottom left, select a workspace.

  2. Select Settings on the left navigation sidebar to open your Workspace settings.

  3. 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

Variables added at the repository level can be accessed by any users with the push permission in the repository.

From the repository, you can manage repository variables in 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 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.

Use SSH keys in Bitbucket Pipelines

You'll want to set up an SSH key in Bitbucket Pipelines if:

  • your build needs to authenticate with Bitbucket or other hosting services to fetch private dependencies.

  • your deployment needs to authenticate with a remote host or service before uploading artifacts.

  • you want builds to use tools such as SSH, SFTP or SCP.

An SSH public and private key pair must be added to the Bitbucket Cloud repository and the public key must be added to the remote service or machine.

When you set an SSH key on a Bitbucket repository, all users with write access to the repo will have access to the remote host. 

Bitbucket requires PEM format for the key. If you use a custom key in a different format other than PEM, you’ll get an error.

You should be able to push and pull to your Bitbucket Cloud repo with no problems. But, if you need to use SSH, for example, to use a bot account, or when branch permissions are enabled, see Set up an SSH key.

For SSH with Bitbucket repos see:

Not all available Docker images have SSH installed by default. If you are using the default pipelines image you'll be fine, but if you need to specify your own image, make sure SSH is either already installed, or install it with your script.

For example, depending on your image, including in your script:

apt-get update -y
apt-get install -y ssh

Steps to use SSH keys in Pipelines

Step 1: Add an SSH key in Bitbucket

We recommend that you generate a new SSH key pair, but you can use an existing key pair if your key requirements differ from the Bitbucket 2048-bit RSA keys. Whichever way you add an SSH key, the private key is automatically added to the build pipeline (as an additional SSH key), and doesn't need to be specified in the bitbucket-pipelines.yml file.

If your Docker image already has an SSH key your build pipeline can use that key, and you don't need to add an SSH key in this step – go to Step 2!

Any SSH key you use in Pipelines should not have a passphrase.

Note that Bitbucket Pipelines supports one SSH key per repository. If you need to use more than one key, you can add them as secured Bitbucket Pipelines environment variables, and reference them in the bitbucket-pipelines.yml file. See the Use multiple SSH keys section below.

To generate a new SSH key pair (recommended):

  1. In the repository Settings, go to SSH keys under 'Pipelines'.

  2. Click Generate keys to create a new SSH key pair.

Now go to Step 2 below.

To add an existing key pair:

You can use an existing key pair if your key requirements differ from the Bitbucket 2048-bit RSA keys. For security reasons, you should never add your own personal SSH key – you should use an existing bot key instead.

  1. In the repository Settings, go to SSH keys

  2. Paste the private and public keys into the provided fields, then click Save key pair.

Step 2: Update the known hosts

Pipelines provides a way for you to store, and inspect, the fingerprint of a remote host, along with the host address. This allows you to visually verify that the public key presented by a remote host actually matches the identity of that host, to help you detect spoofing and man-in-the-middle attacks. It also means that future communications with that host can be automatically verified.

In the repository Settings, go to SSH keys, and add the address for the known host. Click the Fetch button to see the host's fingerprint. Note: Bitbucket Pipelines automatically adds the fingerprint for the Bitbucket and GitHub sites to all pipelines (but doesn't display that in the UI shown above).

Step 3: Add the public key to a remote host

You must install the public key on the remote host before Pipelines can authenticate with that host. If you want your Pipelines builds to be able to access other Bitbucket repos, you need to add the public key to that repo.

Remote hosts

If you have SSH access to the server, you can use the ssh-copy-id  command. Typically, the command appends the key to the ~/.ssh/authorized_keys file on the remote host:

1 ssh-copy-id -i my_ssh_key username@remote_host

Test the SSH access to the server:

1 ssh -i ~/.ssh/my_ssh_key user@host

If you are creating, rather than modifying the .ssh files you may need to change their permissions

  • chmod 700 ~/.ssh

  • chmod 600 ~/.ssh/authorized_keys

Other Bitbucket Cloud repositories

If you want your Pipelines builds to be able to access a different Bitbucket repository (other than the repo where the builds run):

  1. Add an SSH key to the settings for the repo where the build will run, as described in Step 1 above (you can create a new key in Bitbucket Pipelines or use an existing key).

  2. Add the public key from that SSH key pair directly to settings for the other Bitbucket repo (i.e. the repo that your builds need to have access to). 
    See Access keys for details on how to add a public key to a Bitbucket repo.

Use multiple SSH keys in your pipeline

Bitbucket Pipelines supports one SSH key per repository. However, you can use multiple keys with a pipeline by adding them as secured variables, and referencing them in the bitbucket-pipelines.yml file. Follow the steps below to set up and use multiple SSH keys in your pipeline.

1: Generate an SSH key (if necessary) 

Generate an RSA key pair without a passphrase. On Linux or OS X, you can run the following in a terminal:

1 $ ssh-keygen -t rsa -b 4096 -N '' -f my_ssh_key

2: Encode the private key

Pipelines does not currently support line breaks in environment variables, so base-64 encode the private key by running:

Linux

1 $ base64 -w 0 < my_ssh_key

Mac OS X

1 $ base64 < my_ssh_key

3: Add the key as a secure variable

There are security risks associated with passing private SSH keys as repository variables:

  • Repository variables get copied to child processes that your pipelines build may spawn.

  • Secured variables can be retrieved by all users with write access to a repository.

We recommend that you never pass your own personal SSH key as an repository variable, but instead generate a new SSH key-pair for Pipelines that easily be disabled if it is compromised. It may also be worth using deployment variables, which you can combine with deployment permissions to control access.

Copy the encoded key from the terminal and add it as a secured Bitbucket Pipelines environment variable for the repository:

  1. In the Bitbucket repository, choose Settings, then Repository variables.

  2. Copy the base64-encoded private key from the terminal.

  3. Paste the encoded key as the value for an environment variable. Make sure to check Secured.

Secured highlighted with box checked

4: Install the public key on a remote host

Add the public key to the remote host as described in ‘Step 3: Add the public key to a remote host’ in the above procedure.

5: Create the my_known_hosts file and add it to your repo

The known_hosts file contains the DSA host keys of SSH servers accessed by the user. It's important to verify that you're connecting to the correct remote host. Note that Bitbucket Pipelines automatically adds the fingerprint for the Bitbucket and GitHub sites to all pipelines.

  1. Create the my_known_hosts file that includes the public SSH key of the remote host. You can do this by executing the following command:

    1 $ ssh-keyscan -t rsa server.example.com > my_known_hosts
  2. Commit the my_known_hosts file to your repository from where your pipeline can access it.

Alternatively, you can copy an existing known_hosts file from the ~/.ssh directory of a user who has previously accessed the remote host via SSH. You can remove all unrelated lines.

6: Tie everything together in the bitbucket-pipelines.yml file

Pipelines spins up a new Docker container environment for every build. You can use the SSH key by referencing it in the bitbucket-pipelines.yml file. 

To reference the SSH key for Docker containers that run your pipelines:

1 2 3 4 5 6 7 8 9 image: node:6 # specify your Docker image here pipelines: default: - step: script: - mkdir -p ~/.ssh - cat my_known_hosts >> ~/.ssh/known_hosts - (umask 077 ; echo $MY_SSH_KEY | base64 --decode > ~/.ssh/id_rsa) - ssh <user>@<host> 'echo "connected to `host` as $USER"'

The example above just connects to the host and echoes "connected to 'host' as <user>".

Note that the ssh command in the final line will use your default SSH identity. To specify a different key, use the -i option like this:

1 ssh -i ~/.ssh/my_other_ssh_key <user>@<host>

You can also modify the last line to use scp to transfer files or git to clone files from a remote server via SSH.

Last modified on Oct 27, 2020
Cached at 12:37 AM on Nov 26, 2020 |

Additional Help

Ask the Community