GitHub Personal Access Token Setup

This guide walks you through creating a GitHub fine-grained Personal Access Token (PAT) with the correct permissions for your AI coding tools (Claude Code, Copilot, Cursor, etc.) to create issues, manage project boards, push code, and create branches in our organisation repos.

Why Fine-Grained PATs?

GitHub offers two types of PATs:

Type	Scope control	Recommendation
Classic PAT	Coarse — repo grants full read, write, and delete on all repos	Avoid for daily use
Fine-grained PAT	Granular — pick exact permissions per-repository	Use this

Classic PATs bundle everything under repo. This means your AI tool has permission to delete repositories, manage webhooks, and modify admin settings — none of which it should ever do. Fine-grained PATs let you grant only what's needed.

Limitation: Projects (v2) Not Supported

Fine-grained PATs do not support GitHub Projects (v2) permissions yet. This means you cannot use a fine-grained PAT to add issues to project boards via the CLI.

Workaround: Use the fine-grained PAT for daily work (code, issues, PRs). When you need to add an issue to a project board, either:

• Do it via the GitHub web UI, or
• Temporarily escalate with gh auth refresh -s project -h github.com, complete the task, then switch back.

---

Prerequisites

The org owner must enable fine-grained PATs for the organisation:

1. Go to https://github.com/organizations/jod-app/settings/personal-access-tokens
2. Set "Allow access via fine-grained personal access tokens" to enabled
3. Recommended: Set "Do not require approval" for team velocity (or require approval if you prefer tighter control)

If this setting is not enabled, you will not see jod-app in the Resource owner dropdown when creating a token.

---

Step 1: Create the Token

1. Go to https://github.com/settings/personal-access-tokens/new
2. Fill in:
   • Token name: claude-code (or whatever describes the tool)
   • Expiration: 90 days (rotate quarterly)
   • Resource owner: Select jod-app (NOT your personal account)
   • Repository access: Select "Only select repositories" and pick the repos you work on (e.g., jodapp-api, jodapp-web)

Step 2: Set Permissions

Under Repository permissions, set the following:

Permission	Access	Why
Contents	Read and write	Push commits, create branches, read code
Issues	Read and write	Create and comment on issues
Pull requests	Read and write	Create and review PRs
Metadata	Read	Always required (auto-selected)

Leave everything else as No access. Specifically, do NOT grant:

Permission	Why not
Administration	Allows deleting repos, managing webhooks, deploy keys
Actions	Only needed to enable/disable workflows or download artifacts — not to trigger CI
Environments	Only needed to manage deployment environments
Secrets	Only needed to manage repo secrets
Workflows	Only needed to modify .github/workflows/ files — grant only if you edit CI config

tip

The Actions permission does not control triggering CI. Workflows trigger from pushes and PR events, which are covered by Contents and Pull requests. You only need Actions if you manage workflow files or download artifacts via the API.

Step 3: Configure gh CLI

# Option A: Login with the token interactively
gh auth login -h github.com

# When prompted:
#   - Account: GitHub.com
#   - Protocol: SSH (recommended) or HTTPS
#   - Authenticate: "Paste an authentication token"
#   - Paste your fine-grained PAT

# Option B: Login with the token from a file
echo "github_pat_xxxxx" | gh auth login --with-token

Verify

gh auth status

You should see output like:

github.com
  ✓ Logged in to github.com account your-username (keyring)
  - Active account: true
  - Git operations protocol: ssh
  - Token: github_pat_****
  - Token scopes: none (fine-grained PAT — scopes shown differently)

Verify access

# Should list repos you selected
gh repo list jod-app --limit 5

# Should work
gh issue list --repo jod-app/jodapp-api --limit 3

---

Step 4: Rotate Your Token

Fine-grained PATs expire. Set a calendar reminder to rotate before expiry.

1. Go to https://github.com/settings/tokens?type=beta
2. Click your token → Regenerate token
3. Run gh auth login again with the new token

---

Quick Reference

What your AI tool CAN do with these permissions

• Create and push branches
• Create commits
• Create and comment on issues
• Create and review pull requests
• Read repository contents

What your AI tool CANNOT do

• Delete repositories or branches (no Administration)
• Modify webhooks or deploy keys (no Administration)
• Access or modify secrets (no Secrets)
• Enable/disable GitHub Actions workflows (no Actions)
• Add issues to GitHub Projects v2 (not supported by fine-grained PATs)
• Access repos you didn't explicitly select