github-authenticator

name	github-authenticator
description	Verify and troubleshoot GitHub CLI authentication. Use when gh commands fail with auth errors or when setting up GitHub integration for the first time.
allowed-tools	["Bash(gh auth:*)","Bash(gh config get:*)"]

GitHub Authenticator

Instructions

When to Invoke This Skill

• gh commands fail with authentication errors
• User is setting up GitHub CLI for the first time
• Need to verify current authentication status
• Switching between GitHub accounts
• Troubleshooting permission issues

Standard Workflow

1. Check Current Authentication Status

   gh auth status
   

2. Interpret Output

   • Logged in: Shows username, scopes, and token status
   • Not logged in: Shows "You are not logged in to any GitHub hosts"
   • Token expired: Shows authentication but with errors

3. Handle Authentication Issues

   If not authenticated:

   gh auth login
   

   • Choose: GitHub.com or GitHub Enterprise
   • Choose: HTTPS (recommended) or SSH
   • Authenticate via: Browser (recommended) or Token
   • Complete authentication flow

   If token expired:

   gh auth refresh
   

   If wrong account:

   gh auth logout
   gh auth login
   

Required Scopes

Verify the token has necessary scopes:

• repo - Full control of private repositories
• workflow - Update GitHub Action workflows
• admin:org - Read organization data (if working with org repos)

Error Scenarios

"HTTP 401: Bad credentials"

• Token is invalid or expired
• Run: gh auth refresh or re-authenticate

"HTTP 403: Resource not accessible"

• Insufficient permissions
• Check repository access
• Verify organization membership

"HTTP 404: Not Found"

• Repository doesn't exist
• User doesn't have access
• Check repository name and permissions

Configuration Check

View current configuration:

gh auth status --show-token

(Be careful - this displays the token)

Check which host is configured:

gh config get git_protocol

Set preferences:

gh config set git_protocol https
gh config set editor vim

Examples

Example 1: Authentication check before operations

Action: About to create PR
Step 1: Run gh auth status
Step 2: If authenticated, proceed with PR creation
Step 3: If not, guide user through gh auth login

Example 2: Authentication failure during operation

Error: "gh: HTTP 401: Bad credentials"
Action:
1. Inform user of authentication issue
2. Run gh auth status to diagnose
3. Guide through gh auth refresh or gh auth login
4. Retry original operation

Example 3: First-time setup

User: "Setup GitHub CLI"
Action:
1. Check if gh is installed: gh --version
2. Run gh auth login
3. Guide through authentication flow
4. Verify with gh auth status
5. Test with simple command: gh repo view

Example 4: Switching accounts

User: "I need to use my work GitHub account"
Action:
1. Show current account: gh auth status
2. Logout: gh auth logout
3. Login with work account: gh auth login
4. Verify: gh auth status