Skip to content

Commit 775aa60

Browse files
jdrhynejdrhyne
committed
docs: add GitHub token configuration and debugging scripts
- Add comprehensive documentation for fixing GitHub token permissions - Add diagnostic scripts for troubleshooting token authentication issues - Add scripts to verify token scopes, SSO status, and PAT restrictions - Add setup script for configuring GitHub tokens for issue creation - Document the resolution process for authentication failures
1 parent a3ce659 commit 775aa60

10 files changed

+530
-0
lines changed

‎FIX_GITHUB_TOKEN_PERMISSIONS.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Fix GitHub Token Permissions for Issue Creation
2+
3+
## Current Problem
4+
Your token can:
5+
- ✅ Push to branches
6+
- ✅ Read issues
7+
- ❌ Create issues (missing scope)
8+
9+
## Quick Fix Options
10+
11+
### Option 1: Use Fine-grained Personal Access Token (Recommended)
12+
1. Go to: https://github.com/settings/personal-access-tokens/new
13+
2. Token name: `nutrient-dws-development`
14+
3. Expiration: 90 days
15+
4. Repository access: Selected repositories
16+
- Add: `PSPDFKit/nutrient-dws-client-python`
17+
5. Permissions:
18+
- **Repository permissions:**
19+
- Contents: Read/Write
20+
- Issues: Read/Write
21+
- Pull requests: Read/Write
22+
- Actions: Read (optional)
23+
- Metadata: Read (required)
24+
6. Click "Generate token"
25+
7. Copy the token (starts with `github_pat_`)
26+
27+
### Option 2: Use Classic Personal Access Token
28+
1. Go to: https://github.com/settings/tokens/new
29+
2. Note: `nutrient-dws-development`
30+
3. Expiration: 90 days
31+
4. Select scopes:
32+
- ✅ `repo` (Full control - includes private repos)
33+
- OR just ✅ `public_repo` (if the repo is public)
34+
5. Generate and copy token
35+
36+
## Apply the New Token
37+
38+
### Method 1: GitHub CLI (Recommended)
39+
```bash
40+
# Re-authenticate with new token
41+
gh auth login
42+
43+
# When prompted:
44+
# - Choose: GitHub.com
45+
# - Choose: Paste an authentication token
46+
# - Paste your new token
47+
```
48+
49+
### Method 2: Environment Variable
50+
```bash
51+
# In your terminal
52+
export GITHUB_TOKEN='your_new_token_here'
53+
54+
# Or add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
55+
echo "export GITHUB_TOKEN='your_new_token_here'" >> ~/.zshrc
56+
source ~/.zshrc
57+
```
58+
59+
## Verify Token Works
60+
```bash
61+
# Test creating a simple issue
62+
gh issue create --repo PSPDFKit/nutrient-dws-client-python \
63+
--title "Test Issue (Delete Me)" \
64+
--body "Testing token permissions"
65+
66+
# If successful, close it:
67+
gh issue close <issue-number> --repo PSPDFKit/nutrient-dws-client-python
68+
```
69+
70+
## Security Notes
71+
- Never commit tokens to git
72+
- Use environment variables or gh auth
73+
- Rotate tokens regularly
74+
- Use minimum required scopes

‎check-fine-grained-token.sh‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
#!/bin/bash
2+
3+
echo "Fine-Grained Personal Access Token Analysis"
4+
echo "==========================================="
5+
echo ""
6+
echo "Token type: Fine-grained PAT (github_pat_...)"
7+
echo ""
8+
echo "Fine-grained tokens have repository-specific permissions."
9+
echo "Even with 'Admin' access, you need explicit 'Issues: Write' permission."
10+
echo ""
11+
echo "To fix this:"
12+
echo ""
13+
echo "Option 1: Update your fine-grained token"
14+
echo "1. Go to: https://github.com/settings/personal-access-tokens"
15+
echo "2. Find your current token and click 'Edit'"
16+
echo "3. Under 'Repository permissions' for PSPDFKit/nutrient-dws-client-python:"
17+
echo " - Issues: Read → Write"
18+
echo " - Pull requests: Read → Write (if needed)"
19+
echo "4. Save changes"
20+
echo ""
21+
echo "Option 2: Create a classic token instead"
22+
echo "1. Go to: https://github.com/settings/tokens/new"
23+
echo "2. Create a classic token with 'repo' scope"
24+
echo "3. Use: gh auth login"
25+
echo "4. Paste the new classic token"
26+
echo ""
27+
echo "Classic tokens (ghp_...) have simpler, broader permissions."
28+
echo "Fine-grained tokens (github_pat_...) need explicit permissions per repository."

‎check-sso-status.sh‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
#!/bin/bash
2+
3+
echo "Checking SSO Status for PSPDFKit Organization"
4+
echo "============================================="
5+
echo ""
6+
7+
# Check if the token needs SSO authorization
8+
response=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
9+
-H "Accept: application/vnd.github.v3+json" \
10+
-I https://api.github.com/repos/PSPDFKit/nutrient-dws-client-python 2>&1)
11+
12+
if echo "$response" | grep -q "X-GitHub-SSO:"; then
13+
sso_url=$(echo "$response" | grep "X-GitHub-SSO:" | sed 's/.*authorize?//')
14+
echo "❌ SSO Authorization Required!"
15+
echo ""
16+
echo "The PSPDFKit organization requires SAML SSO authorization."
17+
echo ""
18+
echo "To fix this:"
19+
echo "1. Go to: https://github.com/settings/tokens"
20+
echo "2. Find your current token"
21+
echo "3. Click 'Configure SSO' next to the token"
22+
echo "4. Authorize for 'PSPDFKit' organization"
23+
echo ""
24+
echo "Or visit this URL to authorize:"
25+
echo "https://github.com/orgs/PSPDFKit/sso?authorization_request=$(echo $sso_url | cut -d'=' -f2)"
26+
else
27+
echo "✅ No SSO requirement detected in headers"
28+
fi
29+
30+
echo ""
31+
echo "Testing repository access..."
32+
if gh api repos/PSPDFKit/nutrient-dws-client-python >/dev/null 2>&1; then
33+
echo "✅ Can read repository"
34+
else
35+
echo "❌ Cannot read repository"
36+
fi
37+
38+
echo ""
39+
echo "Testing issue list access..."
40+
if gh issue list --repo PSPDFKit/nutrient-dws-client-python --limit 1 >/dev/null 2>&1; then
41+
echo "✅ Can list issues"
42+
else
43+
echo "❌ Cannot list issues"
44+
fi
45+
46+
echo ""
47+
echo "Testing push access..."
48+
if git ls-remote origin >/dev/null 2>&1; then
49+
echo "✅ Can push to repository"
50+
else
51+
echo "❌ Cannot push to repository"
52+
fi
53+
54+
echo ""
55+
echo "Most likely cause: SAML SSO authorization needed"
56+
echo "Solution: Authorize your PAT for the PSPDFKit organization"

‎diagnose-issue-creation.sh‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
#!/bin/bash
2+
3+
echo "Comprehensive Issue Creation Diagnostic"
4+
echo "======================================="
5+
echo ""
6+
7+
# Test 1: Your user info
8+
echo "1. User Information:"
9+
gh api user --jq '{login, type, site_admin}'
10+
11+
# Test 2: Organization membership
12+
echo ""
13+
echo "2. Organization Relationship:"
14+
echo " Checking if you're a member or outside collaborator..."
15+
is_member=$(gh api orgs/PSPDFKit/members --paginate 2>/dev/null | jq -r '.[] | select(.login == "jdrhyne") | .login' | wc -l)
16+
if [ "$is_member" -gt 0 ]; then
17+
echo " ✅ You are an organization member"
18+
else
19+
echo " ⚠️ You are NOT an organization member (likely outside collaborator)"
20+
echo " This might be the issue - outside collaborators may have restricted API access"
21+
fi
22+
23+
# Test 3: Check teams
24+
echo ""
25+
echo "3. Team Membership:"
26+
gh api orgs/PSPDFKit/teams --paginate 2>/dev/null | jq -r '.[].name' | head -5 || echo " Cannot access team information"
27+
28+
# Test 4: Repository access type
29+
echo ""
30+
echo "4. Repository Access Type:"
31+
echo " You have: Admin permissions"
32+
echo " Can create PRs: Yes"
33+
echo " Can push: Yes"
34+
echo " Can create issues via API: No"
35+
36+
# Test 5: Possible explanations
37+
echo ""
38+
echo "5. Possible Explanations:"
39+
echo " a) You're an outside collaborator with admin access"
40+
echo " - Outside collaborators can have limited API access even with admin permissions"
41+
echo " - This is a GitHub security feature"
42+
echo ""
43+
echo " b) Repository-specific API restrictions"
44+
echo " - Some repos can have custom API restrictions"
45+
echo ""
46+
echo " c) Token type mismatch"
47+
echo " - Fine-grained tokens might need explicit issue permissions even for admins"
48+
49+
# Test 6: Workarounds
50+
echo ""
51+
echo "6. Recommended Solutions:"
52+
echo " a) Create issues via the web interface at:"
53+
echo " https://github.com/PSPDFKit/nutrient-dws-client-python/issues/new"
54+
echo ""
55+
echo " b) Ask an organization member to:"
56+
echo " - Add you as an organization member (not just collaborator)"
57+
echo " - Or create the issues on your behalf"
58+
echo ""
59+
echo " c) Use the GitHub web UI to paste the issue content from:"
60+
echo " ./github_issues/*.md files"
61+
62+
# Final test
63+
echo ""
64+
echo "7. Testing Web Access:"
65+
echo " Open: https://github.com/PSPDFKit/nutrient-dws-client-python/issues/new"
66+
echo " If you CAN create issues there, you're an outside collaborator with API restrictions"

‎final-diagnosis.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Final Diagnosis: Issue Creation Problem
2+
3+
## The Situation
4+
- Repository created: June 17, 2025 (very recent)
5+
- You have full admin access
6+
- Can perform all operations EXCEPT create issues via API
7+
- Error: "Resource not accessible by personal access token"
8+
9+
## Most Likely Cause: Fine-Grained PAT Repository Access
10+
11+
Since you're using a fine-grained personal access token (github_pat_...), and this repository was created AFTER your token, the issue is likely:
12+
13+
**Your fine-grained PAT was created before this repository existed, so it doesn't include this repository in its access list.**
14+
15+
Fine-grained PATs have repository-specific access lists. When you create a token, you select which repositories it can access. Repositories created after the token won't automatically be included.
16+
17+
## Solution
18+
19+
### Option 1: Update Your Existing Token
20+
1. Go to: https://github.com/settings/personal-access-tokens
21+
2. Find your current token
22+
3. Click the pencil icon to edit
23+
4. Under "Repository access", ensure `PSPDFKit/nutrient-dws-client-python` is explicitly selected
24+
5. Under "Repository permissions", verify:
25+
- Contents: Write
26+
- Issues: Write
27+
- Pull requests: Write
28+
6. Save the token
29+
30+
### Option 2: Create a New Token
31+
1. Go to: https://github.com/settings/personal-access-tokens/new
32+
2. Select "All repositories" OR explicitly add `PSPDFKit/nutrient-dws-client-python`
33+
3. Set permissions:
34+
- Contents: Write
35+
- Issues: Write
36+
- Pull requests: Write
37+
4. Generate and use the new token
38+
39+
### Option 3: Use a Classic Token
40+
Classic tokens don't have repository-specific restrictions:
41+
1. Go to: https://github.com/settings/tokens/new
42+
2. Select `repo` scope
43+
3. Generate and use this token
44+
45+
## Why This Happens
46+
- Fine-grained PATs must explicitly list each repository
47+
- New repositories aren't automatically added to existing tokens
48+
- This explains why you can do everything else (push, PRs) but not create issues - the API might have different permission checks
49+
50+
## Verification
51+
After updating your token, test with:
52+
```bash
53+
gh auth login # Use the updated token
54+
gh issue create --repo PSPDFKit/nutrient-dws-client-python --title "Test" --body "Test"
55+
```

‎fix-gh-auth.sh‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
#!/bin/bash
2+
3+
echo "Fixing GitHub CLI Authentication for Issue Creation"
4+
echo "=================================================="
5+
echo ""
6+
echo "Current situation:"
7+
echo "- GITHUB_TOKEN environment variable is set with limited permissions"
8+
echo "- This is overriding GitHub CLI's stored credentials"
9+
echo ""
10+
echo "To fix this, run these commands:"
11+
echo ""
12+
echo "1. Temporarily unset the GITHUB_TOKEN environment variable:"
13+
echo " unset GITHUB_TOKEN"
14+
echo ""
15+
echo "2. Login to GitHub CLI with a new token that has issue write permissions:"
16+
echo " gh auth login"
17+
echo ""
18+
echo " When prompted:"
19+
echo " - Choose: GitHub.com"
20+
echo " - Choose: HTTPS"
21+
echo " - Choose: Paste an authentication token"
22+
echo " - Generate a new token at: https://github.com/settings/tokens/new"
23+
echo " - Required scopes: 'repo' (or at least 'public_repo' + 'write:issues')"
24+
echo " - Paste the new token"
25+
echo ""
26+
echo "3. Verify the new authentication:"
27+
echo " gh auth status"
28+
echo ""
29+
echo "4. Test issue creation:"
30+
echo " gh issue create --repo PSPDFKit/nutrient-dws-client-python --title 'Test' --body 'Test'"
31+
echo ""
32+
echo "Alternative: If you want to keep using GITHUB_TOKEN:"
33+
echo "- Generate a new token with 'repo' scope"
34+
echo "- Export it: export GITHUB_TOKEN='new_token_with_repo_scope'"
35+
echo ""
36+
echo "Note: The gh CLI stored credentials take precedence over GITHUB_TOKEN when both exist."

‎setup-github-token-for-issues.sh‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
#!/bin/bash
2+
3+
echo "GitHub Token Setup for Issue Creation"
4+
echo "====================================="
5+
echo ""
6+
echo "Your current token can push to branches but not create issues."
7+
echo "You need to create a new Personal Access Token with additional scopes."
8+
echo ""
9+
echo "Steps to create a new token:"
10+
echo ""
11+
echo "1. Open this URL in your browser:"
12+
echo " https://github.com/settings/tokens/new"
13+
echo ""
14+
echo "2. Give your token a descriptive name:"
15+
echo " Example: 'nutrient-dws-client-development'"
16+
echo ""
17+
echo "3. Set expiration (recommended: 90 days)"
18+
echo ""
19+
echo "4. Select the following scopes:"
20+
echo " ✓ repo (Full control of private repositories)"
21+
echo " - This includes:"
22+
echo " ✓ repo:status"
23+
echo " ✓ repo_deployment"
24+
echo " ✓ public_repo"
25+
echo " ✓ repo:invite"
26+
echo " ✓ security_events"
27+
echo " ✓ workflow (if you need to update GitHub Actions)"
28+
echo ""
29+
echo "5. Click 'Generate token'"
30+
echo ""
31+
echo "6. Copy the generated token (it starts with 'ghp_')"
32+
echo ""
33+
echo "7. Run this command to update your GitHub CLI authentication:"
34+
echo " gh auth login"
35+
echo ""
36+
echo " - Choose: GitHub.com"
37+
echo " - Choose: Paste an authentication token"
38+
echo " - Paste your new token"
39+
echo ""
40+
echo "Alternative: Set token as environment variable:"
41+
echo " export GITHUB_TOKEN='your_new_token_here'"
42+
echo ""
43+
echo "To verify your new token has the correct scopes:"
44+
echo " gh api user -H 'Accept: application/vnd.github.v3+json' --include | grep X-OAuth-Scopes"
45+
echo ""
46+
echo "The output should show: X-OAuth-Scopes: repo, workflow"
47+
echo ""
48+
echo "Once set up, you can create issues with:"
49+
echo " gh issue create --repo PSPDFKit/nutrient-dws-client-python --title 'Test' --body 'Test issue'"
50+
echo ""
51+
52+
# Make the script provide current status
53+
echo "Current authentication status:"
54+
gh auth status
55+
56+
echo ""
57+
echo "Checking if we can access the PSPDFKit org repos:"
58+
gh api orgs/PSPDFKit/repos --paginate --jq '.[].name' | grep -E "^nutrient-dws-client-python$" || echo "Cannot access PSPDFKit repositories with current token"

0 commit comments

Comments
 (0)