Use SSH keys in Bitbucket Pipelines
You'll want to set up an SSH key in Bitbucket Pipelines if:
- your build pipeline needs to authenticate with Bitbucket or other hosting services to fetch private dependencies.
- your deployment pipeline needs to authenticate with a remote host or service before uploading artifacts.
Note that setting up an SSH key allows access to remote hosts for all users with write access to the Bitbucket repository.
On this page
To set up remote host SSH authentication for Bitbucket 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!
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):
- In the repository Settings, go to SSH keys under 'Pipelines'.
- 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.
- In the repository Settings, go to SSH keys.
- Paste the private and public keys into the provided fields, then click Save key pair:
Step 2: Update the known hosts
The host fingerprint allows you to visually verify that the public key presented by a remote host actually matches the identity of that host, helping to avoid spoofing and man-in-the-middle attacks. Storing the fingerprint in Bitbucket locally along with the host address 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 Fetch to see the host's fingerprint:
Note that 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.
Bitbucket Cloud repositories
If you want to access some other Bitbucket Cloud repository as part of your Pipelines builds, you can add the public key directly to the Bitbucket repo (see Use access keys in Bitbucket), perhaps after having generated the key in Pipelines as described in Step 1 above.
All other 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:
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 Bitbucket Pipelines environment variables, and referencing them in the bitbucket-pipelines.yml file.
Step 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:
Step 2: Encode the private key
Pipelines does not currently support line breaks in environment variables, so base-64 encode the private key by running:
Step 3: Add the key as a secure environment variable
Copy the encoded key from the terminal and add it as a secured Bitbucket Pipelines environment variable for the repository:
- In the Bitbucket repository, choose Settings, then Environment variables.
- Copy the base64-encoded private key from the terminal.
- Paste the encoded key as the value for an environment variable. Make sure to check Secured.
See Environment variables in Bitbucket Pipelines for more information.
Step 4: Install the public key on a remote host
Add the public key to the remote host as described above.
Step 5: Create the
known_hosts file and add it to your repo
The known_hosts file contains 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.
my_known_hostsfile that includes the public SSH key of the remote host. You can do this by executing the following command:
- Commit the
my_known_hostsfile 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 that has previously accessed the remote host via SSH. You can remove all unrelated lines.
Step 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 configure SSH for Docker containers that run your pipelines:The example above just connects to a server and echoes "connected to <server> as <user>". You can modify the last line to use
scpto transfer files or
gitto clone files from a remote server via SSH.
Was this helpful?
Thanks for your feedback!