This page provides information regarding setting up your Jenkins instance to use SSH credentials for communication with Bitbucket. This workflow is applicable when using the Git plugin.

Generate SSH key pair

Before configuring Bitbucket and Jenkins, you must first generate the SSH key each will use. There are many different options for generating an SSH key, and you can use whichever method meets the requirements set by your organization. These examples generate an SSH key with the ed25519 algorithm from the command line in macOS, Microsoft Windows 10 and 11, and Linux. The process for generating ssh keys on each platform is quite similar.

macOS Terminal

The example key uses the ed25519 algorithm to generate the key, does not use a passphrase, and saves to the default location.

Open Finder > Applications > Utilities > Terminal. The Terminal window opens.
Enter ssh-keygen -t ed25519 at the command prompt and press ENTER.
Press ENTER to save the key to the default location.
Press ENTER to not include a passphrase and again to confirm.
The SSH key pair is created and saved to the directory.
Copy the key to the clipboard with the pbcopy command. The example pbcopy < ~/.ssh/id_ed25519.pub uses the default save location. If you are using a different key type (RSA, ECDSA), substitute ed25519 with the alternative key type.
With the key copied to the clipboard, you can quickly and easily paste the key to Bitbucket and Jenkins.

You are currently in Webhook to Jenkins for Bitbucket Cloud documentation. Click Server/Data Center to move to that document.

In this section

Windows 10 and 11 Command Prompt

Windows 10 and 11 have a built-in OpenSSH client that you can use to generate an SSH key. As in the previous example, the ssh key does not use a passphrase and saves to the default location.
Press the Windows key on the keyboard or click the Windows icon and type cmd when the Start menu opens. Under Best Match, click Command Prompt.
1. Enter ssh-keygen -t ed25519 at the command prompt and press ENTER.
2. Press ENTER to save the key to the default location (c:/[home_directory]/.ssh).
3. Press ENTER to not include a passphrase and again to confirm.
  The SSH key pair is created and saved to the directory.
4. To access the ssh public key, press the Windows button on your keyboard and type File Explorer. Under Best match, select File Explorer. Go to [home directory]/.ssh for the default save location.
5. Open the public key file (the public key has a .pub extension) and copy the key to the clipboard. With the key copied to the clipboard, you can quickly and easily paste the key to Bitbucket and Jenkins.

Linux Terminal

The example key uses the ed25519 algorithm to generate the key, does not use a passphrase, and saves to the default location.

From Terminal, enter ssh-keygen -t ed25519 at the command prompt and press ENTER.
Press ENTER to save the key to the default location.
Press ENTER to not include a passphrase and again to confirm.
The SSH key pair is created and saved to the directory.
Copy the key to the screen with the cat command. The example cat ~/.ssh/id_ed25519.pub uses the default location. If you use a different key type (RSA, ECDSA), substitute ed25519 in the filename with the alternative key type.
Highlight the key and copy it to the clipboard. With the key copied to the clipboard, you can quickly and easily paste the key to Bitbucket and Jenkins.

Bitbucket configuration

Click your profile avatar and select Personal Settings. Your Personal Settings page opens.
From the side menu, select SSH keys.
Click Add Key to open the Add SSH keys dialog.
Add a Label to help manage multiple SSH keys and paste your SSH key in the Key field.
Click Add Key.

Jenkins configuration

Log into your Jenkins instance.
Add or select the job you want to associate with your Bitbucket repository.
Once you are in the job, click Configure from the left menu.
Select the Source Code Management tab and the Git option when the Configuration page opens.
In the Repository URL field, enter the URL for the Bitbucket repository you want Jenkins to integrate with.
Click Add to open the Jenkins Credentials Provider dialog.
Select SSH Username with private key from the Kind pulldown list.
Provide the following information:
- Scope - Leave this at the default Global credentials setting.
- ID (optional) - Set this to help better identify this specific configuration. If left blank, Jenkins generates an ID.
- Description (optional) - Add a description to help differentiate between credentials.
- Username - Use the same email address used to log into Bitbucket.
- Treat username as secret (optional)- masks the username in the build log.
- Enter directly - Select this option. When the Key field appears, click Add and enter the SSH private key.
- Passphrase - If you included a passphrase when you generated the SSH key, add it here; otherwise, leave the field empty.
Scroll to the bottom of the page and click Save.

While in the Source Code Management section, scroll down to Build Triggers and confirm the selected Poll SCM option. This option is required when using Webhook to Jenkins for Bitbucket Cloud.

Git host key verification

Once you have finished adding the SSH key information to Bitbucket and Jenkins, you may still encounter an error similar to:

No RSA host key is known

This results from how Jenkins verifies the SSH keys presented by the Git repository host servers. By default, the Git plugin uses the Known hosts file method to verify keys. The key is not verified if the host server is not in the file, and Jenkins returns an error message.

One option is to go to Manage Jenkins > Configure Global Security and scroll down until you reach Git Host Key Verification Configuration. Under the Host Key Verification Strategy, switch from Known hosts file to Accept first connection.

With this option selected, Jenkins remembers the first host key encountered for each git server and requires the same key for future access.

Configure SSH Credentials for Webhook to Jenkins for Bitbucket