Skip to content

appendix-d-git-authentication.md

Latest commit

 

History

History
336 lines (234 loc) · 10.7 KB

appendix-d-git-authentication.md

File metadata and controls

336 lines (234 loc) · 10.7 KB

Appendix D: Git Authentication

SSH Keys & Personal Access Tokens

Audience: This appendix is for contributors who need to configure Git authentication for push access. If you're working entirely through the GitHub web interface or GitHub Desktop, you can skip this. If you're using VS Code with Git command line, this becomes relevant when you want to push commits to your fork.

When You Need Authentication

GitHub requires authentication when you:

  • Push commits to a repository
  • Clone a private repository
  • Access organization repositories with specific permissions

You do not need authentication to:

  • Clone public repositories
  • View public repositories on GitHub.com
  • Read issues and pull requests

Two Authentication Methods

Personal Access Token (PAT)

A Personal Access Token is a password-like string you generate on GitHub and use instead of your account password when Git asks for credentials.

Pros:

  • Works on all operating systems
  • Easy to set up for screen reader users (no command line required)
  • Can be scoped to specific permissions
  • Easy to revoke if compromised

Cons:

  • You have to store it securely
  • Expires after a set time (you must regenerate)

SSH Keys

SSH uses public-key cryptography. You generate a key pair on your computer (public + private), upload the public key to GitHub, and Git uses the private key to prove your identity.

Pros:

  • Once set up, works automatically (no password prompts)
  • More secure than tokens
  • Never expires

Cons:

  • Requires command-line setup (less accessible for some screen reader users)
  • Slightly more complex initial configuration

Creating a Personal Access Token (Recommended for This Workshop)

Why this method: It's screen reader accessible through the GitHub web interface, and you can complete it without command-line Git configuration.

Step 1: Generate the Token

  1. Navigate to github.com/settings/tokens
  2. Select "Tokens (classic)" from the left sidebar
  3. Activate "Generate new token" → Select "Generate new token (classic)"
  4. Give it a descriptive name in the Note field: "Workshop Laptop Token"
  5. Set expiration: 30 days or 60 days (recommended for temporary workshop use)
  6. Select scopes:
    • repo - Full control of private repositories (includes public repo access)
    • workflow - Update GitHub Actions workflows (if you'll work with Actions)
  7. Scroll down and activate "Generate token"
  8. CRITICAL: Copy the token immediately - you cannot see it again

Screen reader note: The token appears as a long string in a text field. Select all (Ctrl+A), copy (Ctrl+C), and paste it into a secure note or password manager.

Step 2: Store It Securely

Options:

  • Password manager (1Password, Bitwarden, LastPass) - best option
  • Encrypted note in your operating system's secure notes
  • Plain text file in an encrypted folder (temporary only)

Do not:

  • Paste it into a document you sync to cloud storage unencrypted
  • Email it to yourself
  • Save it in a public GitHub file

Step 3: Use It

The next time Git asks for your password (when you push, pull from a private repo, or clone a private repo):

Username: [your-github-username]
Password: [paste-your-PAT-here]

Windows Git Credential Manager: Windows will remember this token automatically after your first use. You only paste it once.

macOS Keychain: macOS will offer to save it to Keychain. Select "Always Allow."

Linux: You can configure Git to cache credentials:

git config --global credential.helper cache

Setting Up SSH Keys (Alternative Method)

If you prefer SSH and are comfortable with terminal commands:

Step 1: Check If You Already Have a Key

ls -al ~/.ssh

Look for files named id_rsa.pub, id_ed25519.pub, or similar. If you see these, you already have a key.

Step 2: Generate a New SSH Key

ssh-keygen -t ed25519 -C "your-email@example.com"

When prompted:

  • Press Enter to accept the default file location
  • Enter a passphrase (optional but recommended)

Screen reader note: Git will print output showing where the key was saved. It generates two files: id_ed25519 (private) and id_ed25519.pub (public).

Step 3: Copy Your Public Key

Windows (PowerShell):

Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard

macOS:

pbcopy < ~/.ssh/id_ed25519.pub

Linux:

cat ~/.ssh/id_ed25519.pub
# Manually select and copy the output

Step 4: Add to GitHub

  1. Navigate to github.com/settings/keys
  2. Select "New SSH key"
  3. Title: "Workshop Laptop SSH Key"
  4. Key type: Authentication Key
  5. Key: Paste your public key (should start with ssh-ed25519 or ssh-rsa)
  6. Select "Add SSH key"
  7. Confirm with your password or 2FA code

Step 5: Test the Connection

ssh -T git@github.com

You should see: Hi username! You've successfully authenticated...

Step 6: Use SSH URLs

When cloning or adding remotes, use SSH URLs instead of HTTPS:

# SSH format:
git@github.com:owner/repo.git

# Instead of HTTPS:
https://github.com/owner/repo.git

Switching Between HTTPS and SSH

If you cloned with HTTPS but want to use SSH (or vice versa), update the remote:

Check your current remote:

git remote -v

Switch to SSH:

git remote set-url origin git@github.com:your-username/repo.git

Switch to HTTPS:

git remote set-url origin https://github.com/your-username/repo.git

Troubleshooting

"Authentication failed" when pushing

Problem: Your token expired or is incorrect.

Solution:

  • Generate a new PAT
  • Clear your credential cache (Windows: Credential Manager; macOS: Keychain; Linux: git credential-cache exit)
  • Try pushing again - Git will ask for credentials

"Permission denied (publickey)"

Problem: SSH key not properly set up.

Solution:

  • Verify your key is added to GitHub: github.com/settings/keys
  • Check SSH agent is running: ssh-add -l
  • Add your key to the agent: ssh-add ~/.ssh/id_ed25519

"Host key verification failed"

Problem: SSH doesn't recognize GitHub's host key.

Solution:

ssh-keyscan github.com >> ~/.ssh/known_hosts

Security Best Practices

  1. Never share your private key or PAT - treat them like passwords
  2. Use scoped PATs - only grant the minimum permissions needed
  3. Set expiration dates on PATs - regenerate periodically
  4. Use a passphrase on SSH keys - adds another layer of security
  5. Revoke old tokens when you're done with a project or device
  6. Don't commit tokens or keys to Git - use .gitignore for config files

Commit Signing - Verified Badges and Vigilant Mode

When you push commits to GitHub, each commit shows a small badge: Verified or Unverified. This badge tells anyone viewing the commit history whether the commit was cryptographically signed - proving it came from you and was not tampered with.

Why It Matters

Open source maintainers increasingly require signed commits before merging. Some repositories enforce this with branch protection rules. If you contribute to accessibility-agents and your commits show "Unverified," a maintainer may ask you to sign them before the PR can be merged.

Two Methods for Signing Commits

SSH Signing (simpler - reuses your existing SSH key)

If you already have an SSH key set up for authentication, you can use it for signing too.

Step 1: Configure Git to use SSH for signing:

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

Step 2: Add your SSH key as a signing key on GitHub:

  1. Navigate to github.com/settings/ssh
  2. Select "New SSH key"
  3. Change "Key type" to "Signing Key" (not Authentication Key)
  4. Paste your public key and save

Your commits now show the Verified badge in GitHub's commit history.

GPG Signing (traditional method)

Step 1: Generate a GPG key:

gpg --full-generate-key
# Choose: RSA and RSA, 4096 bits, never expires
# Enter your GitHub email address when prompted

Step 2: Find your key ID:

gpg --list-secret-keys --keyid-format=long
# Output includes: sec   rsa4096/XXXXXXXXXXXXXXXX
# The X's are your key ID

Step 3: Export the public key:

gpg --armor --export YOUR_KEY_ID
# Copies the block starting with -----BEGIN PGP PUBLIC KEY BLOCK-----

Step 4: Add to GitHub:

  1. Navigate to github.com/settings/gpg-keys
  2. Select "New GPG key" → paste the exported public key

Step 5: Configure Git to sign all commits:

git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true

Vigilant Mode

GitHub has an optional setting called Vigilant Mode (in Settings → SSH and GPG Keys → Vigilant mode). When enabled, GitHub marks all commits from your account as "Unverified" unless they are signed - even commits that were previously shown without a badge.

Why some maintainers enable Vigilant Mode:

  • It makes tampered or spoofed commits immediately obvious
  • It signals that the repository cares about commit provenance

What you see as a contributor:

  • Every unsigned commit you push will show a yellow "Unverified" badge
  • This is a visual signal - commits can still be pushed, but maintainers may block the merge

To read verification badges with a screen reader:

  • Navigate to the repository's commit history (Code tab → Commits link)
  • Each commit row contains either "Verified" or "Unverified" as a badge element
  • NVDA/JAWS: the badge is inside the commit row; use ↓ to read through each row and the badge text is read inline
  • VoiceOver: use VO+Right through the commit row; the badge is read as a button with the text "Verified" (clicking it shows the certificate)

Workshop recommendation: SSH signing is simpler to set up than GPG and reuses your existing key. If you have 10 minutes, configure it before Day 2 - every commit you push to accessibility-agents will show as Verified.

For This Workshop

Recommended approach:

  1. Generate a Personal Access Token with 30-day expiration
  2. Scope: repo and workflow
  3. Store it in your password manager
  4. Use it when VS Code or Git asks for a password

SSH keys are great for long-term use, but PATs are faster to set up and more accessible for screen reader users during a time-constrained workshop.

Return to: Pre-Workshop Setup | Resources