GitHub Personal Access Tokens: Create, Use and Secure Fine-Grained Tokens

GitHub no longer accepts passwords for Git and API access. In this lesson you will learn every way to authenticate, create a fine-grained personal access token with minimal permissions, use it safely with Git, the API and CI, and fix common token errors.

---

🔑 How GitHub Authenticates Git and Tools

GitHub does not accept your account password for Git operations over HTTPS or for the API. Instead you use one of these:

Method	Best for	Lesson
Git Credential Manager (browser sign-in)	Everyday HTTPS use on Windows and macOS	Configure Git
SSH keys	Developers, Linux, many repositories	SSH keys
Personal access token (PAT)	Scripts, API calls, tools, HTTPS without a credential manager	This lesson
GITHUB_TOKEN	GitHub Actions workflows (automatic)	Secrets and environments
GitHub CLI (gh auth login)	Terminal work with GitHub	GitHub CLI

A personal access token is a long, random string that acts like a password with limited permissions and an expiry date.

---

🧩 Fine-Grained vs Classic Tokens

	Fine-grained token	Classic token
Repository access	Selected repositories only (or all)	All repositories you can access
Permissions	Detailed per area (Contents, Issues, Pull requests…)	Broad scopes (repo, workflow…)
Expiry	Required	Optional (can be “no expiration”)
Organisation approval	Can be required by the organisation	Not available
Recommendation	✅ Use by default	Only when a tool does not support fine-grained tokens yet

---

🛠️ Create a Fine-Grained Token

1. On GitHub, open your profile picture menu, Settings, Developer settings, Personal access tokens, Fine-grained tokens.
2. Click Generate new token.
3. Token name: something descriptive, such as “Local test runner – git-practice”.
4. Expiration: choose a short period (for example 30 or 90 days).
5. Resource owner: you or your organisation.
6. Repository access: Only select repositories, then choose the repositories.
7. Permissions: grant only what is needed, for example:

Task	Repository permission
Clone, pull and push code	Contents: Read and write
Read code only	Contents: Read-only
Create or comment on issues	Issues: Read and write
Open or update pull requests	Pull requests: Read and write
Edit workflow files in .github/workflows	Workflows: Read and write

1. Click Generate token and copy it immediately: GitHub shows it only once.

---

💻 Use a Token with Git over HTTPS

When Git asks for credentials:

Username: your-github-username
Password: <paste the token here>

A credential helper stores it so you are not asked every time:

git config --global credential.helper manager    # Git Credential Manager (Windows; also on macOS/Linux if installed)
git config --global credential.helper osxkeychain  # macOS Keychain
git config --global credential.helper store      # plain-text file (avoid on shared machines)

---

🌐 Use a Token with the GitHub API

# Read the token from an environment variable, never type it in the command itself
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
     -H "Accept: application/vnd.github+json" \
     https://api.github.com/user/repos

On Windows PowerShell set it for the session with $env:GITHUB_TOKEN = "<token>", or load it from a .env file in your scripts.

---

🤖 Tokens in CI and Automation

• In GitHub Actions, prefer the built-in GITHUB_TOKEN: it is created for each run, scoped to the repository and expires automatically. Set its permissions with the permissions: key in the workflow.
• When you need access to another repository (for example a private submodule), store a fine-grained PAT or a deploy key as an encrypted secret, never in the workflow file.
• For organisation-wide automation, a GitHub App is often better than a personal token tied to one person.

---

🔄 Manage Tokens

• Regenerate before expiry (GitHub emails a reminder).
• Revoke tokens you no longer use.
• For organisations with SAML single sign-on, authorise the token for the organisation (Configure SSO next to the token).
• Check Settings, Security log for unexpected token use.

---

🐞 Troubleshooting

Error	Cause and fix
Support for password authentication was removed	You entered your account password; use a token, SSH or Git Credential Manager
403: Permission denied / Resource not accessible	Token lacks the permission or repository access; edit the token
refusing to allow a Personal Access Token to create or update workflow	Add the Workflows permission (or workflow scope for classic tokens)
Git keeps using an old token	Remove the stored credential (Windows Credential Manager, macOS Keychain) and try again

---

📝 Assignment

1. Create a fine-grained token with access only to git-practice, Contents read and write, expiring in 7 days.
2. Clone git-practice over HTTPS in a new folder and push a commit using the token.
3. Call https://api.github.com/user with the token from an environment variable.
4. Revoke the token and confirm that pushing fails.
5. Write down which authentication method you will use day to day, and why.

---

❓ FAQ

🤔 What is a GitHub personal access token?

A generated credential that replaces your password for Git over HTTPS, the GitHub API and tools, with limited permissions and an expiry date.

🤔 How do I create a personal access token in GitHub?

Go to Settings, Developer settings, Personal access tokens, Fine-grained tokens, Generate new token; choose repositories, permissions and an expiry, then copy the token.

🤔 Fine-grained or classic token: which should I use?

Fine-grained tokens, because they can be limited to specific repositories and permissions. Use classic tokens only when a tool requires them.

🤔 Where do I use the token when Git asks for a password?

Enter your GitHub username, then paste the token in the password field.

🤔 What should I do if my token is leaked?

Revoke it immediately in Developer settings, create a new one with minimal permissions, and check the security log.

---

🎯 Next Steps

• 🛡️ Branch Protection Rules and Rulesets
• 🔐 Secrets, Dependabot and Code Scanning
• 📘 Git and GitHub Tutorial: full course