Docs
Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Rotate project SSH keys

1 week ago5 min read
Cloud
Server v4+
On This Page

To revoke usage of a project SSH key, rotate the key pairs by following the steps outlined below. There are separate instructions for each supported version control system (VCS).

When using project SSH keys, CircleCI holds the private key, and the target system (typically a VCS, machine, or another SSH based system) holds the matching public key via its authorization system. To rotate SSH keys both the private and public keys need to be removed.

GitHub projects

Go to Project Settings  SSH Keys to view SSH keys set up for your project.

Rotate a deploy key (GitHub OAuth App)

Only relevant to projects using GitHub OAuth App:

  1. Take note of the current key information to rotate, including the fingerprint. You can also click the keyname to open the related GitHub page that should list the public key.

  2. Delete the deploy key by clicking the X.

  3. Add a new deploy key by clicking Add Deploy Key.

  4. Go to GitHub’s repository project settings to delete the matching public key. The GitHub URL is typically https://github.com/<org>/<project>/settings/keys, or you may already have the page open if you clicked on the keyname in step 1. The keys are named CircleCI. Removing any key titled CircleCI created before the rotation is recommended. The new public SSH key will be automatically added once the old key is deleted.

Rotate a user key (GitHub OAuth App)

Only relevant to projects using GitHub OAuth App. If you have set up user keys for your project, follow these steps:

  1. Take note of the current key information to rotate, including the fingerprint. You can also click the keyname to open the related GitHub page that should list the public key.

  2. Delete the user key by clicking the X.

  3. Add a new user key by clicking Add User Key.

  4. Go to GitHub’s User settings to delete the matching public key. The GitHub URL is typically https://github.com/settings/keys or you may already have the page open if you clicked on the keyname in step 1. Removing any key titled CircleCI created before this rotation is recommended. The new public SSH key will be automatically added once the old key is deleted (page may need to be refreshed to view the key).

Rotate an additional SSH key (GitHub OAuth App & GitHub App)

Relevant to projects that use the GitHub OAuth App and projects that use the CircleCI GitHub App. If you are using additional SSH keys in your project, follow these steps:

  1. Take note of the existing key to know which target system it is used for, and the fingerprint for your records. This could be a VCS, a machine, or another SSH based system.

  2. Delete the SSH key by clicking the X.

  3. The key will need to be recreated manually, for example, using OpenSSH (ssh-keygen -t ed25519 -C "your_email@example.com"). Instructions can be found on GitHub’s documentation.

  4. Add the new key to CircleCI by clicking Add SSH Key under the Additional SSH Keys section. The hostname can be the same as for the old key you just removed. Paste in the private key you created in the step above and click Add SSH Key again to finalize.

  5. Remove the authorization to use the old key from the target system. Typically, the public key will be authorized in the target system, and the configuration varies depending on the target system.

  6. Authorize the target system to use the new key.

Bitbucket projects

Go to Project Settings > SSH Keys to view SSH keys set up for your project.

Rotate a deploy key

  1. Take note of the current key information to rotate.

  2. Delete the deploy key by clicking the X.

  3. Add a new deploy key by clicking Add Deploy Key.

  4. Go to Bitbucket’s project admin access-key settings to delete the matching public key. The Bitbucket URL is typically https://bitbucket.org/<org>/<project>/admin/access-keys/. The keys are named CircleCI. Since the fingerprint hash is not shown, it is recommended to remove any key titled CircleCI created before the rotation. The new public SSH key will be automatically added once the old key is deleted (page may need to be refreshed to view the key).

Rotate a user key

  1. Take note of the current key information to rotate.

  2. Delete the user key by clicking the X.

  3. Add a new user key following the Create a Bitbucket user key instructions.

  4. Go to Bitbucket’s user account settings to delete the matching public key. The Bitbucket URL is typically https://bitbucket.org/account/settings/ssh-keys/. The user names the keys, therefore, CircleCI does not know if the key name contains the string CircleCI. It is recommended to remove any key created before the rotation.

Rotate an additional SSH key

  1. Take note of the existing key’s hostname to know which target system it is used for, and the fingerprint for your records. The target could be a VCS, a machine, or another SSH based system.

  2. Delete the SSH key by clicking the X.

  3. The key will need to be recreated manually, for example, using OpenSSH (ssh-keygen -t ed25519 -C "your_email@example.com"). Instructions can be found on Bitbucket’s documentation.

  4. Add the new key to CircleCI by clicking Add SSH Key under the Additional SSH Keys section. The hostname can be the same as for the old key you just removed. Paste in the private key you created in the step above and click Add SSH Key again to finalize.

  5. Remove the authorization to use the old key from the target system. Typically, the public key will be authorized in the target system, and the configuration varies depending on the target systems.

  6. Authorize the target system to use the new key.

GitLab projects

Go to Project Settings > SSH Keys to view SSH keys set up for your project. The GitLab CI integration with CircleCI does not use deploy keys or user keys.

Rotate an SSH key

  1. Take note of the existing key and fingerprint to be able to match the target system it is used for, typically gitlab.com.

  2. Delete the SSH key by clicking the X.

  3. The key will need to be recreated manually, for example, using OpenSSH (ssh-keygen -t ed25519 -C "your_email@example.com"). Instructions can be found on GitLab’s documentation.

  4. Add the private key by clicking Add SSH Key. It is recommended you name the key gitlab.com. Paste in the private key you created in the step above and click Add SSH Key again to finalize.

  5. Go to your GitLab project’s settings for the repository (Settings > Repository) and expand the Deploy keys section. The keys are named circleci-pipeline-triggers and you can match the fingerprint. It is recommended to remove any key created before the rotation.

  6. Add the new key. For consistency, you can name the key in the title section circleci-pipeline-triggers. Paste the public key and click Add key to finalize.

Rotate an additional SSH key

In some scenarios, you might also be using additional SSH keys that are not tied to GitLab.

  1. Take note of the existing key’s hostname to know which target system it is used for, and the fingerprint for your records. The target could be a VCS, a machine, or another SSH based system.

  2. Delete the SSH key by clicking the X.

  3. The key will need to be recreated manually, for example, using OpenSSH (ssh-keygen -t ed25519 -C "your_email@example.com"). Instructions can be found on GitLab’s documentation.

  4. Add the new key to CircleCI by clicking Add SSH Key under the Additional SSH Keys section. The hostname can be the same as for the old key you just removed. Paste in the private key you created in the step above and click Add SSH Key again to finalize.

  5. Remove the authorization to use the old key from the target system. Typically, the public key will be authorized in the target system, and the configuration varies depending on the target systems.

  6. Authorize the target system to use the new key.

Suggest an edit to this page

Make a contribution
Learn how to contribute

Still need help?

Ask the CircleCI community
Join the research community
Visit our Support site