Configure SSH Credentials for Webhook to Jenkins for Bitbucket

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. This example generates an SSH key using ed25519 on the Terminal application in macOS. The example 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 < ~/.ssh/id_ed25519.pub command. With the key copied to the clipboard, you can quickly and easily paste the key to Bitbucket and Jenkins. If you are using a different key type (RSA, ECDSA), substitute ed25519 with the alternative key type.

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

In this section

Bitbucket Cloud 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 in managing 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 as the one 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 the passphrase here; otherwise, leave blank.
Scroll to the bottom of the page and click Save.

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

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 is a result of 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. If the host server is not in the file, the key is not verified 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 that the same key for future access.