What we need

[] API Token [] Organization

Creating a GitHub API Token

This guide provides step-by-step instructions for creating a GitHub API token with the necessary permissions for a GitHub admin user to access repositories, commits, teams, and members information.

Prerequisites

• Admin access to the GitHub organization
• A GitHub account that is a member of the organization with admin privileges

Creating a Personal Access Token (Classic)

1. Log in to GitHub with the admin account

2. Navigate to Settings

   • Click on your profile picture in the top-right corner
   • Select “Settings” from the dropdown menu

3. Access Developer Settings

   • Scroll down to the bottom of the left sidebar
   • Click on “Developer settings”

4. Create a Personal Access Token

   • Select “Personal access tokens” from the left sidebar
   • Click on “Fine-grained tokens”
   • Click the “Generate new token” button. If you have 2-factor authentication enabled, enter your 2-factor code to continue.

5. Configure Token Settings

   • Token name: Provide a descriptive name (e.g., “Parable GitHub Integration”)

   • Description: Put in a description that is recognizable to you.

   • Resource owner: click the drop down and select the organization you’d like to integrate with. The default is

   • Expiration: Select an appropriate expiration period (recommended: 360 days)

   • Repository access: Select “All repositories”, or if you want limited access, you can select “Only select repositories” and pick the repos you’d like to grant read access to.

     Permissions: Click “Add Permissions”.

     Organization permissions With the “Organizations” tab highlighted in the bar below “Choose the minimal permissions necessary for your needs.”:

     • Select “members”, “organization admnistration”, “organization events’, “organization projects”, and “team discussions”, with each given “read” access.

     Repository permissions With the “Repositories” tab highlighted in the bar below “Choose the minimal permissions necessary for your needs.”, select:

     • “Pull requests”
     • “Issues”
     • “Discussions”
     • “Commit statuses”
     • “Contents”
     • “code”
     • “metadata” and select “read” for all the permissions.

6. Generate Token

   • Scroll to the bottom of the page
   • Click “Generate token”

7. Copy and Secure the Token

   • IMPORTANT: Copy the generated token immediately and store it securely
   • GitHub will only display the token once for security reasons
   • Consider using a secure password manager to store the token

Verifying Token Permissions

To verify that your token has the correct permissions:

1. Use the token to make a test API call:

   curl -H "Authorization: Bearer YOUR_TOKEN" https://api.github.com/user
   

2. If successful, you should receive your user information in the response

3. Test organization access:

   curl -H "Authorization: Bearer YOUR_TOKEN" https://api.github.com/orgs/YOUR_ORGANIZATION/members
   

Security Considerations

• Treat the token like a password; never share it in public repositories or communications
• Use the shortest expiration time that is practical for your use case
• Consider using GitHub’s SAML SSO if your organization uses it for additional security
• Regularly audit and rotate tokens to maintain security
• If a token is compromised, immediately revoke it in GitHub settings

Troubleshooting

• 403 Forbidden errors: Check that the token has the correct permissions
• 401 Unauthorized errors: The token may have expired or been revoked
• Rate limit exceeded: GitHub API has rate limits (5,000 requests per hour for authenticated requests)
• Organization access issues: Ensure the token owner has the necessary organization permissions

Additional Resources

• GitHub API Documentation
• GitHub Personal Access Tokens
• GitHub API Rate Limits