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.
- learn how to set up two-factor authentication
- learn how to set up a personal access token
- GitHub account
- Git installed on your computer
- Access to a Unix shell
- Basic command line skills
- Github documentation on two-factor authentication
- Github documentation on personal access token
- Github documentation on updating credentials
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.
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.
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.
If you normally enter your user name and password when you
git pushlocal 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 config --list
On a MacOS, it may show:
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.
You may want to
git pusha 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
For other options to update your Github credentials with the PAT key, see the Github documentation.