Access remote hosts via SSH
You can set up SSH authentication for Bitbucket Pipelines for simplified SSH, SFTP, and SCP access to remote hosts directly from your build pipeline.
Setting up the authentication makes remote hosts accessible via SSH to all users with the write access to the repository.
On this page
To set up remote host SSH configuration for Bitbucket Pipelines:
Step 1: Generate an SSH key pair
First, generate an RSA key pair without a passphrase. On Linux or OS X, open the terminal and run:
$ ssh-keygen -t rsa
4096 -N '' -f my_ssh_key
||The script generates a key pair. For more information, see keygen|
||The type of the key is RSA|
The size of the key is 4096 bits for better security
|The key pair doesn't require a passphrase. Keys that are used in scripts don't require passphrases|
|The key file names will start with
The output of the command might look like this:
Generating public/private rsa key pair. Your identification has been saved in my_ssh_key. Your public key has been saved in my_ssh_key.pub. The key fingerprint is: <your_key_fingerprint> The key's randomart image is: <your_key_randomart>
The script creates two files:
||Your private key|
||Your public key|
You can check whether the files exist by running the following command:
$ ls -a
Step 2: Encode the private key and add it as a secure environment variable
Currently, Pipelines doesn't support line breaks in environment variables. To make sure that your SSH private key goes safely through the Bitbucket Pipelines GUI, base-64 encode it by running:
$ base64 < my_ssh_key
Copy the output of the command from the terminal and add it as a Bitbucket Pipelines environment variable called
- Go to Account > Bitbucket Settings.
- Select an individual account or a team for which you want to configure variables.
- In the menu on the left, go to Pipelines > Environment variables.
- Copy the output of the base64 command from the terminal.
- Paste the command output as the value of the secured
For more information, see Environment variables in Bitbucket Pipelines.
The variable that contains your private SSH key is present in the list of Bitbucket Pipelines variables:
Step 3: Install the public key on a remote host
To make the authentication between Pipelines and a remote host possible, you must install the public key on the remote host. Bitbucket lets you upload keys from the GUI, other remote hosts might require some manual setup.
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 in Bitbucket Cloud as described in Add an SSH key to an account. Once you add your public key to Bitbucket Cloud, you can proceed to Step 4 of this guide.
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.
$ ssh-copy-id -i my_ssh_key.pub firstname.lastname@example.org
|The script that copies the public key to a remote host. For more information, see ssh-copy-id.|
|The key file that will be copied|
|The details of the remote host into which you want to copy the public key|
$ ssh -i my_ssh_key email@example.com
Note: The command just opens a prompt within the terminal.
Step 4: 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 for verification that you're connecting to the correct remote host.
my_known_hostsfile that includes the public SSH key of the remote host. You can do this by executing the following command:
$ ssh-keyscan -t rsa server.example.com > my_known_hosts
- Commit the
my_known_hostsfile to your repository from where your pipeline can access it.
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.
Now you can run SSH-based commands for the configured remote host without passwords.
Here's an example of uploading a file using SFTP:
$ sftp firstname.lastname@example.org <<< $'put file-to-upload.txt'
Step 5: Tie everything together in your bitbucket-pipelines.yml file
Pipelines spin up a new Docker container environment for every build. You can make the SSH configuration accessible by adding it to the bitbucket-pipelines.yml file.
To configure SSH for Docker containers that run your pipelines:
mkdir -p ~/.ssh
|Creates the .ssh directory and its parents in the Docker container|
cat my_known_hosts >> ~/.ssh/known_hosts
|Adds the list of known hosts with your remote host details to the list of known hosts in the Docker container|
(umask 077 ; echo $MY_SSH_KEY | base64 --decode > ~/.ssh/id_rsa)
base64: invalid input error
Your bitbucket-pipelines.yml file can look like this:
The example above just connects to a server and echoes "connected to <server> as <user>". You can modify the last line to use
scp to transfer files or
git to clone files from a remote server via SSH.
The clone asks for a passphrase
Things that you can check:
- The SSH key pair that you created in Step 1 must be created without a passphrase.
- The private SSH key that you generated is base64 encoded as described in Step 2.
Was this helpful?
Thanks for your feedback!