Github CircleCI Authentication

Automatically update GitHub repository content by authenticating CircleCI to push commits directly to GitHub

Primary goal: Being a part of a small startup, the amount of time we put to solve the problems could be saved for other upcoming startups.

Vantashala

Initial Setup:

1. Created GitHub repository
2. Activated CI builds for the repository on CircleCI

If you haven’t done this, see the CircleCI documentation Getting Started.

Overview

Authenticating CircleCI server to commit the artifact (e.g., report, plot, documentation) generated by CircleCI job on your behalf to GitHub.

When we authenticate CircleCI to build a GitHub repository for the first time, it adds a Read-Only deploy key to our GitHub repo. This can be found in GitHub Repo → Settings → Deploy Keys

This Deploy key has rights only to read the GitHub repository(e.g. GIT Checkout, Git Pull).To push the Generated Report on CircleCI docker, we need Read and Write Key.

We have 3 ways to Authenticate CircleCI. In the following sections, we discuss it in detail.

Authentication Options

1. Generating the SSH key pair from git bash locally and configure private and public keys
2. Generate Personal Access Token(PAT) from Git hub
3. SSH user key

Let’s drill down each option

1. Generating an SSH key pair from git bash locally and configure private and public keys

1.1 Create SSH key pair

This will only be used by CircleCI to authenticate with this one GitHub repository.

You can follow the standard instructions from GitHub for generating a new SSH key if you are doing it for the first time.

This created the private key /c/Users/you/.ssh/id_ed25519 and the public key /c/Users/you/.ssh/id_ed25519.pub.

Points to be Noted:

For the key to work, it must be in PEM format. The private key field that has the following header and footer is not in PEM format

-----BEGIN OPENSSH PRIVATE KEY-----
-----END OPENSSH PRIVATE KEY-----

GitHub understands these keys, but CircleCI returns an HTTP 400 when trying to add this as an SSH Key

The solution I found was to change the ssh-keygen command to include -m PEM

ssh-keygen -m PEM -t rsa -C "your_email@example.com"  # force PEM format

This specifically tells ssh-keygen to use the PEM format (which was(?) the default, but not anymore), and outputs a key with the usual header/footer:

-----BEGIN RSA PRIVATE KEY-----
-----END RSA PRIVATE KEY-----

1.2. Add the public key to GitHub

Navigate to your GitHub Repo → Settings → Deploy keys

Click Add deploy Key to add a new key.

Then copy-paste the contents of the public key /c/Users/you/.ssh/id_ed25519.pub into the Key field.

Lastly, check the box “Allow write access” so that CircleCI can push back to GitHub.

You see a deploy key with read/write access, added to your repo.

Deploy keys for GitHub repository. The top one is the default Read-only deploy key added automatically by CircleCI. The bottom one is the new Read/write deploy key.

1.3. Add the private key to CircleCI

Next, navigate to the project on CircleCI. The URL follows the pattern: https://circleci.com/gh/<account>/<repo>.

Don’t click on the “Organization Settings” in the menu on the left. That is for Organization.

Instead, click on the gear icon with Project Settings.

Click SSH keys in the menu on the left

Click “Add SSH key”. You can put whatever you like in the Hostname field to remind you that this key is for pushing to GitHub. Copy-paste the private key /c/Users/you/.ssh/id_ed25519 into the field “Private Key”. As the name implies, you shouldn’t expose this key.

Add private key to CircleCI

Once you add Private Key, you will see it displays a fingerprint for the key.

Refer https://medium.com/@praveena.vennakula/test-automation-with-cypress-circleci-mochawesome-5c82c752da4f , for adding fingerprints in config.yml file.

2. Generate Personal Access Token(PAT) from GitHub

You could generate a GitHub PAT, either for your own account or a bot account, with the required scope to write to your repository (public_repo for a public repository, repo for a private repository).

refer GitHub PAT generation

You would then define this as an environment variable in your CircleCI build (e.g., GITHUB_PAT) in the Project Settings → Environment Variables → Add Environment Variable.

This would authenticate you to push to your repository using the following URL pattern: https://workflowr:$GITHUB_PAT@github.com/<account>/<repo>.git.

It is not possible to limit the scope of a PAT to a single repository. In other words, if a PAT with write permissions is exposed, it gives write access to every repository owned by that account.

3. SSH user key

CircleCI has a convenient option to register a user key. In the CircleCI project settings page → SSH Keys → Checkout SSH keys → Authorize with GitHub

This will add a public key to your GitHub account, and CircleCI keeps the private key.

Now your CircleCI build will be able to access all of your public and private repositories on GitHub. If your CircleCI build needs write access to multiple repositories (or read access to multiple private repositories), I recommend this option. If you only need write access to one repository, it is more secure to use a deploy key since it has limited access to your account.