Skip to content

Setting up Github Authentication

By mid-2021, Github will complete its transition to requiring a personal access token (PAT) key instead of a password to connect to Github remotely (e.g., using git on your local computer to work on remote branches).

In this tutorial, we will show you how to enable two-factor authentication (optional) and generate a PAT.

Learning Objectives

  • learn how to set up two-factor authentication
  • learn how to set up a personal access token

30 mins

  • GitHub account
  • Git installed on your computer
  • Access to a Unix shell
  • Basic command line skills

Step 1: Go to Github account settings

  • Click on Settings from the top-right dropdown menu on your Github profile picture.

Step 2a: Set up two-factor authentication

While this step is optional, it is a good security measure to protect your account.

  • Click on Account security. On this page, scroll past the change password section to the two-factor authentication section.

  • Click Enable two-factor authentication.

Step 2b: Choose how to receive codes

There are two options for receiving the two-factor authentication code.

The recommended method is to receive the code from a phone app, such as Authy, 1Password, or LastPass Authenticator. The Duo Security app also works. For this option, click Set up using an app.

The second option is to receive the code via text message to your phone. This option is only available in certain countries. For detailed steps on this method, see the Github documentation.

Step 2c: Save recovery codes

The next page will show a series of recovery codes; you will need these codes to regain access to your account if it is ever lost. Download, print, or copy these codes to a safe place, then click Next.

Step 2d: Enable two-factor authentication

If you chose to set up two-factor authentication with a phone app, open the app and scan the QR code. Enter the six-digit code from the app on Github in the text box below the QR code. After you click Enable, the two-factor authentication set up is complete!

You can test by logging out of Github and logging back in - the phone app should send you a six-digit code to enter as part of login.

Step 3a: Generate a PAT

Navigate to Developer settings located on the left panel of Account settings.

This will take you to a new page, on the left panel, click on Personal access tokens.

Click on Generate new token. Give it a name in the Note text box - this can be a nickname to help you remember what the token is for/when it was created.

Scopes enable setting permissions for user access to the various functionality of a repo. To set the scope for your user account, check the box next to repo and select all the tasks pertaining to a private repo that apply.

Update Scope

You can run into OAuth error with tasks if the original PAT doesn't include the correct scope - for example, you may want to include workflow in your scope to edit workflow files remotely:

refusing to allow a Personal Access Token to create or update workflow .... without workflow scope

To update the scopes associated with your PAT, you can do so by:

  • generating a new PAT key with the updated repo scopes
  • delete the GitHub credentials in keychain (on MacOS) or in Git Credential manager (on Windows)
  • delete and update the git credentials (Step 3b)

Alternatively, you can use the Git Credential Manager Core which is a cross platform git credential helper which will request the correct scopes.

Then scroll down and click Generate token.

Warning

Be sure to save the token somewhere safe (e.g., password manager). After you leave this page, the token will no longer be viewable.

The token will look like a string of letters and numbers and appear in the green box just below the warning to make a copy of the token in the blue box. Keep this page open - we will need to use the PAT key instead of our password to login at the command line.

Step 3b: Update keychain with PAT

If you have saved your Github password with a password manager (e.g., osxkeychain on MacOS) to work on Github repositories remotely, it needs to be updated to the PAT we generated. If your Github password is not managed by a password manager, continue to Step 3c.

Note

If you normally enter your user name and password when you git push local changes to Github, you'll need to enter the PAT key instead of your password

From the terminal, check whether the credential.helper is set on your git configurations:

git config --list

On a MacOS, it may show: 

credential.helper=osxkeychain

In this example, we will delete the saved password from osxkeychain, so that it can be updated with the PAT key. Type Enter after each of the commands below at the terminal. After entering protocol=https you need to press Enter twice. If the commands are successful, there should be no output in the terminal.

git credential-osxkeychain erase
host=github.com
protocol=https

Step 3c: Enter PAT as password

The next time you git push changes from your local computer to a remote Github repository, enter your user name and the PAT key from Step 3a as the password.

Tip

You may want to git push a test change (that can be deleted later) to a remote repository you work on now, so that you do not lose the PAT key!

If you have a password manager, it should "remember" the PAT key so it will not need to be entered the next time you use git.

For other options to update your Github credentials with the PAT key, see the Github documentation.

Last update: February 9, 2021