Guides for SE student projects »

Setting up GitHub Authentication

For tools on your computer to interact with GitHub (e.g., pushing a local repository to GitHub), you need to set up a way for them to authenticate you to GitHub. You can use either HTTPS or SSH for this. Both methods are acceptable, but we recommend HTTPS (as does GitHub). That said, Mac and Linux users may find SSH slightly more convenient.

When accessing a GitHub repository, the URL format depends on the protocol you use:

  • HTTPS URLs look like standard web links, starting with https://github.com/
    e.g., https://github.com/johndoe/myrepo.git
  • SSH URLs use a different syntax, starting with git@github.com:
    e.g., git@github.com:johndoe/myrepo.git

Use the matching URL based on the protocol you chose for authentication.

Using HTTPS for authentication

Step 1: Create a Personal Access Token (PAT)

  1. Go to your GitHub account → Settings → Developer settings → Personal access tokens → Tokens (classic).
  2. Click the Generate new token dropdown, and choose Generate new token (classic).
  3. Generate a new token. Specify a suitable description (under Note), an expiration date, and scopes (i.e., operations for which this PAT can be used). We recommend selecting the following scopes:
  4. Copy the token — you’ll need it shortly.

Step 2: Configure Git to cache your credentials

To avoid having to enter username/PAT every time, you can ask Git to store it securely on your computer, as follows:

Windows

Configure Git to use the built-in Credential Manager by running:

git config --global credential.helper manager-core
MacOS

macOS uses the Keychain by default, so your PAT is stored automatically after the first use. No further action needed.

Linux

Configure Git to use credential cache by running:

git config --global credential.helper cache

Step 3: Use the credentials once, to cache it.

When you perform your first Git operation that contacts GitHub (like pushing or pulling), Git will prompt you for a username and password.

  • Enter your GitHub username as the username.
  • Paste the PAT as the password.

To trigger the above step, you can attempt to access a remote private repository:

git clone https://github.com/se-edu/samplerepo-private.git

The operation will fail, but it will trigger the authentication mechanism which will ask for your credentials, and cache them for future use.

Using SSH for authentication

Windows + Git Bash
1. Check for Existing SSH Keys
ls -al ~/.ssh

Look for files like id_ed25519.pub.

2. Create New SSH Key
ssh-keygen -t ed25519 -C "your_email@example.com"
3. Add SSH Key to ssh-agent

In a PowerShell (Admin) window:

Get-Service -Name ssh-agent | Set-Service -StartupType Manual
Start-Service ssh-agent
ssh-add ~/.ssh/id_ed25519
4. Add SSH Key to GitHub

Copy your public key:

cat ~/.ssh/id_ed25519.pub

Then add it to GitHub → Settings → SSH and GPG Keys.

5. Verify SSH Connection
ssh -T git@github.com

Say yes when prompted, and you should see a welcome message with your username.

Windows + WSL

Perform these steps within your WSL distribution.

1. Check for Existing SSH Keys
ls -al ~/.ssh

Look for id_ed25519.pub or similar.

2. Create New SSH Key
ssh-keygen -t ed25519 -C "your_email@example.com"

Press Enter to accept all defaults.

3. Add SSH Key to ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
4. Add SSH Key to GitHub
cat ~/.ssh/id_ed25519.pub

Paste the output into GitHub → Settings → SSH and GPG Keys.

5. Verify SSH Connection
ssh -T git@github.com
MacOS
1. Check for Existing SSH Keys
ls -al ~/.ssh

Look for files named id_rsa.pub, id_ecdsa.pub, or id_ed25519.pub. If you have one, skip to step 4.

2. Create New SSH Key
ssh-keygen -t ed25519 -C "your_email@example.com"

Press Enter to accept all defaults (including empty passphrase).

3. Add SSH Key to ssh-agent

Start the ssh-agent:

eval "$(ssh-agent -s)"

Configure SSH (for macOS Sierra 10.12.2 or later):

touch ~/.ssh/config

Add this to your ~/.ssh/config file:

Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Add your SSH key:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519
4. Add SSH Key to GitHub

Copy your public key to clipboard:

pbcopy < ~/.ssh/id_ed25519.pub
  1. Go to GitHub → Settings → SSH and GPG keys → New SSH key
  2. Give it a name and paste your public key
  3. Save
5. Verify SSH Connection
ssh -T git@github.com

Type yes when prompted, and you should see a message with your username.

Linux
1. Check for Existing SSH Keys
ls -al ~/.ssh

Look for id_ed25519.pub or similar.

2. Create New SSH Key
ssh-keygen -t ed25519 -C "your_email@example.com"

Press Enter to accept all defaults.

3. Add SSH Key to ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
4. Add SSH Key to GitHub
cat ~/.ssh/id_ed25519.pub

Paste the output into GitHub → Settings → SSH and GPG Keys.

5. Verify SSH Connection
ssh -T git@github.com

Contributors: Woo Jiahao (@woojiahao)