Bitbucket User Keys require additional configuration steps to work properly with CircleCI SSH key authentication. This article explains how to generate a User Key from your CircleCI project settings and add it to your Bitbucket repository. User Keys allow CircleCI to access your Bitbucket repository during builds without requiring personal SSH keys from individual developers.

Prerequisites

Before following these instructions, ensure you have:

Admin access to your CircleCI project
Admin access to your Bitbucket repository
Google Chrome browser (these instructions are Chrome-specific)
Basic familiarity with browser developer tools

Instructions

Step 1: Navigate to Project Settings

Go to your CircleCI project's Project Settings page
Click the SSH Keys link in the sidebar

Step 2: Open Browser Developer Tools

Scroll down to the User Key section
Right-click the Add User Key button
Select Inspect from the context menu to open Chrome's developer tools

Step 3: Prepare Network Monitoring

In the developer console, click the Network tab
Click Clear to clear any existing network requests
In the filter box, type checkout (without quotes)
- This filter helps you locate the specific request more easily

Step 4: Generate the User Key

Left-click the Add User Key button to generate the SSH key
Wait for the key generation process to complete

Step 5: Extract the Public Key

In the developer console Network tab, look for a checkout-key request with a 201 status
Click on this checkout-key request
Select the Preview tab in the request details
Locate the public_key value in the response
Copy the entire public key value to your clipboard
- Important: Do not include the surrounding quotes or any line feed characters

Step 6: Add Key to Bitbucket

Navigate to your Bitbucket repository
Go to Repository Settings > Access Keys
Click Add Key
Paste the copied public key value
Give the key a descriptive name (e.g., "CircleCI User Key")
Save the key
Step 7: Configure CircleCI Config. Add the key's fingerprint to your CircleCI configuration by including the add_ssh_keys parameter in your .circleci/config.yml

Outcome

After completing these steps, CircleCI will be able to authenticate with your Bitbucket repository using the User Key during builds. You should see successful SSH authentication in your build logs, and CircleCI will be able to clone your repository and access any private dependencies.

Additional Notes

These instructions are specific to Google Chrome browser. Other browsers may have different developer tool interfaces
The User Key is project-specific and will need to be regenerated if you need to use it with different CircleCI projects
If you encounter a 403 or authentication error after setup, verify that the public key was copied completely without extra characters