GitHub SSH Deprecation Information & Resolutions

On March 15th, 2022 GitHub will be deprecating the types of SSH keys that can be utilized to access their service. With this deprecation, there are circumstances that could cause your builds to fail on the repository checkout step after the 15th. 

If you meet one of the following criteria, you will need to take action before March 15th, 2022:

1. Project created between Nov 2nd, 2021 - January 13th, 2022 that has a job using an Ubuntu 14.04-based machine image, including the default machine: true image

   - If you don’t specify a machine image, you are using the default image and you’ll need to take action

2. Project created between Nov 2nd, 2021 - January 13th, 2022 using deprecated Docker image

3. Project using an uploaded DSA SSH key for checkout purposes

If you meet one of the above, there are sections below that will cover the steps needed to ensure builds continue to run after March 15th, 2022.

You are not affected by the deprecation, if your project meets one of these criteria:

1. Your project was set up before November 2nd, 2021.

2. Your project was set up after January 13th, 2022.

3. Generated a new user/deploy key after January 13th, 2022 and it is your "PREFERRED" key

If your project falls under one of the three items listed directly above, you shouldn't need to take any action before March 15th, 2022. However, if you wish to verify you can check if your key is ed25519 with the following API call:

https://circleci.com/docs/api/v2/#operation/listCheckoutKeys

curl --request GET \
  --url https://circleci.com/api/v2/project/gh/ORG/PROJECT/checkout-key \
  --header 'Circle-Token: '

If the above returns any items that have a "public_key" : "ssh-rsa, and your project was created between November 2nd, 2021 - January 13th, 2022, you will want to ensure you are using a newer image (convenience image or machine image) or you’ll want to regenerate your user/deploy key. If all the keys returned, or your "PREFERRED" key is "public_key" : "ssh-ed25519 then no action should be needed.

Depending on your situation, different actions may be required. If you want to find out the OpenSSH version for the image you are utilizing in a job you can run the following:

run: ssh -V

Jobs using machine: true or specifying a 14.04 ubuntu Machine image

You can tell if you fall into this category if any of your jobs look like this:

jobs:
  build:
    machine: true # This is using the default old machine image
    steps:
      - checkout

Or it may look like this which is an example of a 14.04 based image:

jobs:
  build:
    machine:
      image: circleci/classic:201709-01 # This is a 14.04 based image
    steps:
      - checkout

Additionally, you can search via GitHub for these image uses too:

org:CircleCI-Public circleci/classic path:.circleci filename:config.yml

The following options are available, given the deprecation of older images, our recommendation is to update your image. However, all options listed will solve the issue at hand.

1. Update to a newer machine image any listed on that page have the proper items installed

2. Regenerate your deploy/user key in your project settings

   1. This can be done via the UI (Project Settings → SSH Keys → Click X on the current key)

      1. Once that is done, you’ll click “Add Deploy key” or “Add User key” depending on which type of key you removed

   2. This can also be done via the API

3. Add a run step before your - checkout step that installs OpenSSH 7.2 or greater, as an example, this would install OpenSSH 8.1p1:

jobs:
  jobname:
    machine: true
    steps:
      - run:
          name: Install OpenSSH 8.1p1
          command: |
            sudo apt-get update
            mkdir ~/tempdownload; 
            cd ~/tempdownload; 
            wget https://cdn.openbsd.org/pub/OpenBSD/OpenSSH/portable/openssh-8.1p1.tar.gz; 
            tar zxvf openssh-8.1p1.tar.gz; 
            cd openssh-8.1p1 && ./configure && make && sudo make install
      - checkout

Jobs using circleci convenience images (i.e. circleci/ruby:2.2.6)

The following options are available, given the support for the legacy circleci images is going away, the preferred option is to update your image. However, all options listed will solve the issue at hand.

1. Update to a next-gen convenience image, all next-gen images have the proper items installed

2. Regenerate your deploy/user key in your project settings

   1. This can be done via the UI (Project Settings → SSH Keys → Click X on the current key)

      1. Once that is done, you’ll click “Add Deploy key” or “Add User key” depending on which type of key you removed

   2. This can also be done via the API

3. Add a run step before your - checkout step that installs OpenSSH 7.2 or greater, as an example, this would install OpenSSH 8.1p1:

jobs:
  jobname:
    docker:
      - image: circleci/ruby:2.2.6
    steps:
      - run:
          name: Install OpenSSH 8.1p1
          command: |
            sudo apt-get update
            mkdir ~/tempdownload; 
            cd ~/tempdownload; 
            wget https://cdn.openbsd.org/pub/OpenBSD/OpenSSH/portable/openssh-8.1p1.tar.gz; 
            tar zxvf openssh-8.1p1.tar.gz; 
            cd openssh-8.1p1 && ./configure && make && sudo make install
      - checkout

Jobs using custom or non-circleci Docker images

If the docker image you are utilizing has OpenSSH 7.2 or greater, and git installed, you do not need to make any changes. With both those requirements met, you’ll have no issues with the deprecation. In addition, if your image has neither installed, you'll also not be affected as we'll take care of the checkout process on our side. 

With the above in mind, you'll really only be affected on your custom docker images if you specifically installed an old OpenSSH version.

1. Regenerate your deploy/user key in your project settings

• This can be done via the UI (Project Settings → SSH Keys → Click X on the current key)

  • Once that is done, you’ll click “Add Deploy key” or “Add User key” depending on which type of key you removed

• This can also be done via the API

2. Add a run step before your - checkout step that installs OpenSSH 7.2 or greater, as an example, this would install OpenSSH 8.1p1:

jobs:
  jobname:
    docker:
      - image: koalaman/shellcheck-alpine:v0.7.1
    steps:
      - run:
          name: Install OpenSSH 8.1p1
          command: |
            sudo apt-get update
            mkdir ~/tempdownload; 
            cd ~/tempdownload; 
            wget https://cdn.openbsd.org/pub/OpenBSD/OpenSSH/portable/openssh-8.1p1.tar.gz; 
            tar zxvf openssh-8.1p1.tar.gz; 
            cd openssh-8.1p1 && ./configure && make && sudo make install
      - checkout

3. If git is not installed on the image, you’ll need to install that before the - checkout step, an example of doing that here:

- run:
      name: Install git for checkout
      command: |
          apt-get update && apt-get --no-install-recommends -y install git

4. Swap to a different image, or build a custom image, that has both the proper OpenSSH version and git installed -- or one that doesn't have either installed.

Projects with manually uploaded DSA or RSA SHA1 SSH keys

If you manually uploaded an SSH key to use for checkout purposes, and that key is DSA, you’ll need to update the key to have it continue to work.

You’ll want to generate a new SSH key, meeting the requirements set forth by GitHub, and add and use that key within CircleCI.

If the key you manually uploaded was RSA SHA1:

1. As long as the docker or machine image you are using is new enough, you’ll be able to continue to use the key. The image needs to have OpenSSH 7.2 or greater installed, you can check using the following command in the job using that image: - run: ssh -V

2. Alternatively, if the image you are using is older or you can’t update it, you’ll want to generate a new SSH key, meeting the requirements set forth by GitHub, and add and use that key within CircleCI.

Mass regeneration of checkout keys

For organizations that have a lot of projects, and the option you are proceeding with is regenerating your keys, we have created a script to help with that process:

https://github.com/CircleCI-Public/github-ssh-regeneration

You will want to ensure that the person who runs this script, AKA the personal API key used, has the proper access to generate keys for the repositories. That likely means an Organization Owner/Admin.