Personal Access Tokens (PATs) are essential for modern GitHub workflows. This comprehensive guide covers everything from basic concepts to advanced security practices, helping you implement PATs safely and effectively in your development process.
Quick Tip: If you're using Git-Zen for Zendesk integration, you'll need a PAT with specific permissions. Jump to our
Git-Zen integration section for exact requirements.
What is a Personal Access Token?
A Personal Access Token (PAT) is a secure alternative to using passwords for authentication to GitHub when using the GitHub API or the command line. Think of it as a specialized password that:
- Has specific permissions: Unlike passwords, PATs can be scoped to only allow certain actions
- Can expire: You can set expiration dates for added security
- Is revocable: You can invalidate a token without changing your password
- Works with 2FA: Essential for accounts with two-factor authentication enabled
Important: Treat Personal Access Tokens like passwords. Never share them publicly or commit them to repositories.
Why Use Personal Access Tokens?
GitHub has deprecated password authentication for Git operations and API access. Here's why PATs are superior:
Enhanced Security
- Unique tokens for each application
- Limited scope reduces risk
- Easy to revoke if compromised
- No need to share your password
Better Control
- Granular permission settings
- Expiration dates for compliance
- Audit trail for each token
- Organization-level policies
Types of GitHub Tokens
GitHub offers two types of personal access tokens:
| Feature |
Fine-grained PATs |
Classic PATs |
| Granularity |
Repository-level permissions |
Account-wide permissions |
| Expiration |
Required (max 1 year) |
Optional |
| Repository Access |
Selected repositories only |
All repositories |
| Organization Support |
Requires approval |
Immediate access |
| Best For |
New integrations, enhanced security |
Legacy systems, broad access needs |
Recommendation: Use fine-grained PATs whenever possible. They offer better security through the principle of least privilege.
Creating Your First Personal Access Token
Follow these step-by-step instructions to create your first GitHub Personal Access Token:
1 Access GitHub Settings
Sign in to your GitHub account and click on your profile photo in the upper-right corner. Select Settings from the dropdown menu.
2 Navigate to Developer Settings
In the left sidebar, scroll down and click on Developer settings. This section contains all developer-related configurations.
3 Personal Access Tokens
Click on Personal access tokens and choose between:
- Fine-grained personal access tokens (Recommended)
- Personal access tokens (classic)
Click Generate new token for your chosen type.
4 Configure Token Settings
Fill in the token details:
- Token name: Use a descriptive name (e.g., "Git-Zen Integration")
- Expiration: Set an appropriate expiration date
- Description: Add notes about the token's purpose
- Repository access: Select specific repositories or all repositories
- Permissions: Choose the required scopes (see next section)
5 Generate and Save Token
Click Generate token at the bottom of the page. Your token will be displayed only once!
Critical: Copy your token immediately! You won't be able to see it again. Store it securely in a password manager.
ghp_1234567890abcdefghijklmnopqrstuvwxyz
Understanding Token Permissions
Selecting the right permissions is crucial for security. Here's a detailed guide to common permission scopes:
Repository Permissions
| Permission |
Description |
Use Cases |
repo |
Full control of private repositories |
CI/CD, Git-Zen integration, development tools |
repo:status |
Access commit status |
Build status reporting |
repo_deployment |
Access deployment status |
Deployment automation |
public_repo |
Access public repositories |
Open source contributions |
repo:invite |
Manage repository invitations |
Team management tools |
Workflow Permissions
| Permission |
Description |
Use Cases |
workflow |
Update GitHub Action workflows |
Automated workflow management |
write:packages |
Upload packages to GitHub Package Registry |
Package publishing |
read:packages |
Download packages from GitHub Package Registry |
Package consumption |
delete:packages |
Delete packages from GitHub Package Registry |
Package lifecycle management |
Organization Permissions
| Permission |
Description |
Use Cases |
read:org |
Read organization membership and teams |
Team synchronization, Git-Zen |
write:org |
Manage organization membership |
Automated team management |
admin:org |
Full control of organizations |
Organization automation |
manage_runners:org |
Manage Actions runners |
CI/CD infrastructure |
Security Best Practices
Follow these essential security practices to protect your Personal Access Tokens:
Do's
- Use a unique token for each application
- Set expiration dates (30-90 days recommended)
- Store tokens in environment variables
- Use secret management tools
- Regularly rotate tokens
- Monitor token usage in security logs
- Use fine-grained tokens when possible
- Document token purposes
Don'ts
- Never commit tokens to repositories
- Don't share tokens via email or chat
- Avoid tokens without expiration
- Don't use the same token everywhere
- Never expose tokens in client-side code
- Don't ignore security warnings
- Avoid overly broad permissions
- Don't screenshot tokens
Secure Storage Options
Here are recommended ways to store your PATs securely:
# Environment Variable (Recommended)
export GITHUB_TOKEN="ghp_your_token_here"
# .env file (add to .gitignore!)
GITHUB_TOKEN=ghp_your_token_here
# GitHub Secrets (for Actions)
Settings > Secrets > Actions > New repository secret
# Password Managers
1Password, LastPass, Bitwarden, etc.
Using Tokens in Applications
Here's how to use your Personal Access Token in various scenarios:
Git Command Line
# Clone a private repository
git clone https://<token>@github.com/username/repo.git
# Or use it when prompted for password
Username: your-username
Password: <paste-your-token-here>
# Configure Git to use token
git config --global credential.helper store
GitHub API
# Using curl
curl -H "Authorization: token ghp_your_token_here" \
https://api.github.com/user/repos
# Using JavaScript (Node.js)
const { Octokit } = require("@octokit/rest");
const octokit = new Octokit({
auth: process.env.GITHUB_TOKEN,
});
# Using Python
import requests
headers = {'Authorization': f'token {token}'}
response = requests.get('https://api.github.com/user', headers=headers)
CI/CD Systems
# GitHub Actions
- name: Checkout code
uses: actions/checkout@v3
with:
token: ${{ secrets.GITHUB_TOKEN }}
# Jenkins
withCredentials([string(credentialsId: 'github-token', variable: 'GITHUB_TOKEN')]) {
sh 'git clone https://${GITHUB_TOKEN}@github.com/user/repo.git'
}
# GitLab CI
variables:
GITHUB_TOKEN: $GITHUB_TOKEN
Integrating with Git-Zen
Git-Zen requires specific permissions to synchronize your GitHub repositories with Zendesk tickets. Here's exactly what you need:
For Classic Personal Access Tokens:
repo - Full control of private repositoriesread:org - Read organization membershipwrite:discussion - Write access to discussions (for comments)
For Fine-grained Personal Access Tokens:
- Repository permissions:
- Contents: Read
- Issues: Read and Write
- Pull requests: Read and Write
- Metadata: Read
- Account permissions:
- Organization permissions: Read
Step-by-Step Git-Zen Setup
- Create a dedicated token for Git-Zen with the permissions listed above
- Name it descriptively like "Git-Zen Zendesk Integration"
- Set expiration to 90 days (you'll get reminders to renew)
- Copy the token and navigate to your Git-Zen settings in Zendesk
- Paste the token in the GitHub Personal Access Token field
- Test the connection to ensure everything works
Pro Tip: Create a calendar reminder 7 days before your token expires to ensure uninterrupted service.
Common Issues & Solutions
Encountering problems with your Personal Access Token? Here are solutions to common issues:
Possible causes:
- Token has expired
- Token was revoked
- Incorrect token copied
- Using password instead of token
Solution:
- Verify token hasn't expired in GitHub settings
- Create a new token if needed
- Ensure you're using the token, not your password
- Check for extra spaces when copying
Possible causes:
- Insufficient permissions
- Organization restrictions
- Repository visibility changed
Solution:
- Review token permissions and add required scopes
- Check organization settings for token restrictions
- Request organization approval for fine-grained tokens
- Use a classic token if organization blocks fine-grained
Cause: GitHub no longer accepts passwords for Git operations
Solution:
- Create a Personal Access Token
- Use the token as your password when prompted
- Update your Git credential manager:
git config --global credential.helper manager-core
- Or use SSH keys as an alternative
Possible causes:
- Credentials not being cached
- Credential helper not configured
- Token format issues
Solution:
# Configure credential caching
git config --global credential.helper cache
# Or store permanently (less secure)
git config --global credential.helper store
# For macOS
git config --global credential.helper osxkeychain
# For Windows
git config --global credential.helper wincred
Token Rotation Strategy
Regular token rotation is essential for maintaining security. Here's a comprehensive rotation strategy:
30-Day Tokens
For high-security environments and production systems
- Production deployments
- Financial systems
- Customer data access
90-Day Tokens
Balanced security for most use cases
- Development tools
- CI/CD pipelines
- Integration services
1-Year Tokens
Maximum allowed for fine-grained tokens
- Personal projects
- Low-risk tools
- Read-only access
Rotation Process
- Set reminders 7 days before expiration
- Create new token with same permissions
- Test new token in a non-critical environment
- Update all services with new token
- Verify functionality across all integrations
- Revoke old token after confirming success
- Document rotation in your security log
Important: Never revoke the old token until you've confirmed the new one works in all places!
Frequently Asked Questions
Q: Can I use the same token for multiple applications?
A: While technically possible, it's not recommended. Using unique tokens for each application improves security and makes it easier to track usage and revoke access if needed.
Q: What happens when my token expires?
A: The token will stop working immediately. Any application using it will receive authentication errors. You'll need to create a new token and update all applications using the expired one.
Q: Can I extend a token's expiration date?
A: No, you cannot modify an existing token's expiration. You must create a new token with the desired expiration date.
Q: How many tokens can I create?
A: GitHub doesn't impose a hard limit on the number of tokens, but it's good practice to regularly review and clean up unused tokens.
Q: What's the difference between OAuth apps and Personal Access Tokens?
A: OAuth apps are for third-party applications that need to access multiple users' data, while PATs are for personal use or server-to-server authentication. PATs are simpler to implement but less suitable for multi-user applications.
Ready to Integrate Git-Zen?
Now that you understand Personal Access Tokens, set up Git-Zen to streamline your development workflow.
