Git Guides

Git Guides is an open-source collection of clear, beginner-friendly tutorials that introduce the fundamentals of Git. It provides concise explanations of core concepts, essential commands, and common workflows, offering a reliable starting point for learning how to manage versioned projects and collaborate effectively with Git.

Choosing an Authentication Method for GitHub

Authentication MethodWhen to Use It
SSH Keys (Preferred)For most users performing regular Git operations, especially on trusted personal or work machines. Ideal when you need a secure, long-lived authentication method without entering credentials.
Fine-Grained Personal Access Tokens (FGPATs)When you need highly specific, restricted, time-bound access for scripts, applications, CI/CD systems, or when least-privilege access is required.
Personal Access Tokens (Classic)Only when required by legacy workflows or integrations that do not yet support FGPATs. Best used temporarily or during a transition to more secure authentication.

Setting Up and Using SSH Keys

Generate App State Key
ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/id_ed25519_appstate
Add Key to SSH Agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_appstate


 Add a Public Key to GitHub

Mac
pbcopy < ~/.ssh/id_ed25519_appstate.pub
Linux
cat ~/.ssh/id_ed25519_appstate.pub
Windows (Git Bash)
cat ~/.ssh/id_ed25519_appstate.pub | clip
  1. Log in to GitHub with your username_appstate account.
  2. Open your settings menu, click on SSH and GPG keys, then click New Key.
    Click add new SSH Key.

  3. Paste the key and then click Add.
    Paste in the SSH key and then click Add SSH key.


Edit ~/.ssh/config:

 Personal GitHub

Host github.com
    HostName github.com

    IdentityFile ~/.ssh/id_ed25519_personal


App State GitHub

Host github-appstate
    HostName github.com

App State GitHub (Host github-appstate)
IdentityFile ~/.ssh/id_ed25519_appstate


Clone Repositories

Personal Repo
git clone [email protected]:username/repo.git
App State Repos
git clone git@github-appstate:username_appstate/repo.git

Update Existing Repos

If you already cloned App State repos, update the remote:

git remote set-url origin git@github-appstate:username_appstate/repo.git

Test Connections

Personal Account
ssh -T [email protected]
App State Account
ssh -T git@github-appstate

Alternative: Use HTTPS

Clone with HTTPS and use Personal Access Tokens instead of SSH:

git clone https://github.com/username_appstate/repo.git

To generate a token, open your GitHub settings and click on Developer settings, then Personal Access Tokens


For more information, see  Connecting to GitHub with SSH.

Setting Up and Using Fine-Grained Personal Access Token

Fine-grained personal access tokens (PATs) are a more secure and flexible alternative to classic PATs. They allow users to authenticate with GitHub while granting precise, limited access to specific resources.
Unlike classic PATs, which offer broad access across all repositories and organizations a user can access, fine-grained PATs allow for granular control over:

  • Which repositories the token can access
  • What actions the token can perform (e.g., read-only, write access)
  • Which organization resources are accessible

Advantages Over Classic PATs

  • Tokens are scoped to a single user or organization
  • Access is limited to specific repositories
  • Permissions are explicitly defined per token
  • Organization owners can require approval for tokens accessing their resources

Why Use Classic PATs?

While fine-grained PATs are more secure, classic PATs are still required for certain use cases:

  • Only classic PATs can write to public repositories not owned by you or your organization
  • Outside collaborators must use classic PATs to access organization repositories
  • Some REST API endpoints are only accessible with classic PATs. To check whether an endpoint also supports fine-grained personal access tokens, see the documentation for that endpoint, or see Endpoints available for fine-grained personal access tokens.

Managing Fine-Grained PATs

Treat all PATs like passwords:

  • Do not share them
  • Store them securely (e.g., in a password manager)
  • Revoke them when no longer needed

Create or Manage PATs

You can manage fine-grained PATs from your GitHub account:
Create a Fine-Grained PAT
Steps:

  1. Give the token a descriptive name
  2. Set an expiration date (can be set to "no expiration")
  3. Select the specific repositories the token should access
  4. Choose only the permissions needed for the task
  5. Save and store the token securely

Tip

It’s better to start with minimal permissions and expand only if needed. You can always delete and recreate tokens as necessary.

Sample Use Cases at App State

  • Grant automated tools push/pull access to specific repositories only
  • Allow students to read and respond to GitHub issues without commit access
  • Enable an automation script to manage SSH keys
  • Allow an external application to access a user’s GitHub Copilot license

Setting Up and Using Personal Access Tokens (Classic)

Overview

Personal Access Tokens (PATs) are an alternative to using passwords for authentication to GitHub when using the Git command line or API. They're required when using HTTPS with Git operations.

Managing Personal Access Tokens

  1. Log in to GitHub with username_appstate.
  2. Click your profile photo and then open Settings.


  3. Click on Developer settings at the bottom of the left sidebar.

     
  4. Open the Personal access tokens drop-down menu and select Tokens (classic).


  5. Click the Generate new token drop-down, and select Generate new token (classic).


  6. Configure your token:
    • Note: Add a descriptive note detailing what the token is for
    • Expiration: 90 days (recommended) or custom
    • Select scopes:
      • repo - Full repository control
      • workflow - Update GitHub Actions
      • write:packages - Upload packages (if needed)
      • delete:packages - Delete packages (if needed)
  7. Click Generate token.
  8. Copy the token (you won't see it again).


For more detailed guidance, see Managing your Personal Access Tokens.

Clone with HTTPS

git clone https://github.com/username_appstate/repository.git

When prompted:

  • Username: username_appstate
  • Password: Your PAT (not your actual password)

Store Credentials

Mac/Linux:

git config --global credential.helper cache
# Cache for 1 hour (3600 seconds)
git config --global credential.helper 'cache --timeout=3600'

Windows:

git config --global credential.helper wincred

Update Existing Repository

If you previously used passwords:

git remote set-url origin https://username_appstate:[email protected]/username_appstate/repo.git

Security note: Don't commit tokens in files!

Common Scopes

ScopeUse For
repoPrivate repository access
public_repoPublic repository access only
workflowGitHub Actions workflows
write:packagesUpload to GitHub Packages
read:orgRead organization membership
gistCreate gists

Minimum Scopes

Basic development: repo
GitHub Actions: repo, workflow
Package management: repo, write:packages, read:packages

GitHub offers fine-grained tokens with repository-specific permissions:

  1. Open your Settings, click on Developer settings (at the bottom of the sidebar).


  2.  Click on Personal access tokens drop-down and select Fine-grained tokens.


  3. Click Generate new token.

  4. Configure your token:
    1. Enter a name and description
    2. Select specific repositories
    3. Choose granular permissions
    4. Set a shorter expiration (recommended).
  5. Click Generate Token.
  6. Copy the token (you won't see it again).

Benefits:

  • Repository-specific access
  • Detailed permissions
  • Better security

For detailed guidance, see Creating a Fine-Grained Personal Access Token.

Open your settings, click on developer settings, and then personal access tokens to see:

  • Token names
  • Scopes
  • Last used
  • Expiration dates
  1. Click on the token's name, then click Regenerate token.


  2. Update everywhere you use it.

Click Delete next to the token to delete it immediately.

DO

  • Use descriptive names
  • Set expiration dates
  • Use the minimum required scopes
  • Regenerate regularly
  • Use different tokens for different purposes

DON'T

  • Share tokens
  • Commit tokens to repositories
  • Use tokens in client-side code
  • Reuse tokens across projects

If the token is exposed

  1. Revoke immediately in GitHub settings.
  2. Generate a new token.
  3. Update all applications.
  4. Check for unauthorized access.

Using in CI/CD

Store as repository secret:

  1. Repository → Settings → Secrets and variables → Actions
  2. New repository secret
  3. Name: PAT_TOKEN
  4. Use in workflow:
- uses: actions/checkout@v2
  with:
    token: ${{ secrets.PAT_TOKEN }}

Other CI Systems


Store as an environment variable, never in code!

 

Troubleshooting

  • Verify that the token hasn't expired.
  • Check that the token has required scopes
  • Ensure you are using the token, not password.
  • Check repo scope is selected. 
  • Verifiy repository access permissions. 
  • Generate a new token.
  • Update in all locations.
  • Verify the repo scope. 
  • Check repository permissions. 
  • Confirm token is active.



Resources

  • Managing Personal Access Tokens
  • Token Security Best Practices
  • TaskAction
    Create tokenSettings → Developer settings → Personal access tokens → Generate
    View tokensSettings → Developer settings → Personal access tokens
    Revoke tokenClick Delete next to token
    Use with GitEnter as password when prompted
    Store securelyUse credential helper or secrets management