Documentation structure for LLMs (llms.txt)
CircleCI Logo

Rotate project SSH keys

19 days ago
Cloud Server

To revoke usage of a project SSH key, rotate the key pairs by following the steps outlined below.

When using project SSH keys, CircleCI holds the private key. 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

This section is only relevant to projects in a github type organization:

  1. Take note of the current key information to rotate, including the fingerprint. You can also click the key name to open the related GitHub page that lists 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 key name in step 1. The keys are named CircleCI. Remove any key titled CircleCI created before the rotation. The new public SSH key will be automatically added once the old key is deleted.

Rotate a user key

This section is only relevant to projects in a github type organization:

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 key name to open the related GitHub page that lists 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 key name in step 1. Remove any key titled CircleCI created before this 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).

The user key name contains the project name, however, a user key may give access to more projects within the organization.
If using organization SSO, take note of which org is currently authorized. If access is needed for the newly created key, you will need to reauthorize it.

Rotate an additional SSH key

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.