Create a GitHub Bot Account

Overview

This document explains how to create a U-M GitHub service account.

Context and Problem

A common design pattern is to utilize deploy keys to allow automated processes to fetch a remote git repo, and then use the repo code for steps that follow.

Authentication for such automated processes is normally configured by generating an SSH keypair, giving a service account or process access to the private key, and then installing the public key as a deploy key for each remote repo.

With this type of configuration, one SSH keypair can be used to authenticate to N number of repositories.

Though the above approach is supported by some services (e.g. U-M GitLab), it is not possible in GitHub, which only allows an SSH public key to be assigned to a single repo or a single user.

Solution

This deploy key limitation can be worked around by setting up a service account, i.e. a U-M sponsored account that is linked to to a U-M GitHub account.

An SSH public key can then be installed and associated with the U-M GitHub account.

Finally, the U-M GitHub account can be added to every repo that it needs read access to.

Step-by-Step Process

Create U-M Sponsored Account

If you are an authorized U-M sponsorship admin, create the new service account. If you are not a sponsorship admin, use the information in this section to request a sponsored account via a TeamDynamix ticket, assigned to IAM provisioning and accounts.

1. Select Other University Affiliates from the Reason drop-down list.
   
2. Enter your uniqname in the Requester field.
3. Enter a brief description and purpose of the account in the Notes field.
4. Select one year (minus one day) into the future in the Expiry field.

Note A non-umich.edu email address (that will be assigned to the account to allow password resets) is needed for a later step. Continue through the form prompts to complete the sponsorship.

Change Password and Set Up DUO Two-Factor for Sponsored Account

After the sponsored account has been created:

1. Change the password to use a strong (30+ characters generated by e.g. pwgen or Keepassxc) password. 

2. Set up Duo two-factor, which is required for accessing U-M GitHub.

Create GitHub Account to Link to the new U-M Sponsored Account

1. Navigate to https://github.com in an incognito window.
   Note Using an incognito window will avoid conflicting with your individual GitHub account.
2. Click Sign up.
3. Enter the sponsored account's umich.edu email address in the Enter your email field.
   
4. Enter a strong (30+ character) password in the Create a password field.
   Note The password should be different from the U-M sponsored account password.
5. Enter a username.
   Note The username should be different from the sponsored account uniqname.

Set up Two-Factor for the GitHub Account

Many GitHub orgs enforce a two-factor requirement for GitHub accounts.

1. Click the user icon (upper right) and click Settings.
2. Click Password and authentication.
   
3. Click Enable two-factor authentication.
4. Use Duo (or any other two-factor app that supports TOTP) to scan the QR code you are presented with.
5. Download the recovery codes and store them somewhere safe.

Add SSH Key for GitHub Account

1. Generate a new SSH keypair:

   ssh-keygen

   # Or even better:
   ssh-keygen -t rsa -a 100 -b 4096

   # When prompted, enter a key name (e.g. botkey) so that you do not overwrite any existing, personal SSH keypairs.

2. In order to add the public (.pub) key to the GitHub account, click the user icon (upper right) and click Settings.
3. Click SSH and GPG keys.
   
4. Click New SSH key.
5. Enter an appropriate label for the keypair in the Title field.
6. Select Authentication Key from the Key type drop-down list.
7. Paste the new public key contents (.pub file you generated) in the Key field.
8. Click Add SSH key.

The private key can then be used by processes that need to authenticate as the service account. It is important to keep the private key safe.

Invite GitHub Account to a GitHub Org

Now that the GitHub account is set up with two-factor and with an SSH key, it can be added to U-M GitHub orgs.

1. Ask the appropriate U-M GitHub org owner to invite the service account by GitHub account name or by U-M email address. The role specified in the invitation should be Member.
2. Log in to the U-M sponsored account Gmail to view the invitation.
3. Click Join @org_here in the invitation email.
   
4. On the GitHub page that opens, click Authenticate to join.
5. Click Join @org_here to complete the process.

Configure the SSH Key for the Newly Joined GitHub Org

Any time the service account is added to a new U-M GitHub org, you will need to perform one final step before SSH key authentication works correctly for that org's repos.

1. Click the user icon (upper right) and click Settings.
2. Click SSH and GPG keys.
   
3. Click the Configure SSO drop-down.
4. Click Authorize next to the U-M org the account was added to. This will redirect to the U-M SSO for the sponsored account.
5. After successfully authenticating, the service account is ready for use.

Add the New Service Account to GitHub Repos

The GitHub account can now be added to repos within its new org. (In most cases you will want to add it with only read access.) After adding it to a repo, test cloning using the SSH private key.