GitHub

The GitHub auth provider enables tools and agents to call GitHub APIs  on behalf of a user.

What’s documented here

This page describes how to use and configure GitHub auth with Arcade.

This auth provider is used by:

• The Arcade GitHub MCP Server, which provides pre-built tools for interacting with GitHub
• Your app code that needs to call the GitHub API
• Or, your custom tools that need to call the GitHub API

Why Arcade Uses GitHub Apps (Not OAuth Apps)

Arcade’s Decision

Arcade’s security team selected GitHub Apps over OAuth Apps for the GitHub toolkit based on three critical factors:

1. 🎯 GitHub’s Recommendation: OAuth Apps are soft-deprecated. GitHub actively recommends Apps for new integrations and invests in their development.

2. 🔐 Fine-Grained Security: GitHub Apps support granular permissions (e.g., “Read pull requests”), while OAuth Apps only offer coarse scopes (e.g., repo = full repository access).

3. 🏢 Enterprise Control: Admins can approve exact permissions and see all app installations. OAuth Apps bypass organizational oversight.

Quick Comparison

Why Enterprises Choose GitHub Apps

Creating a GitHub App

For Private Organization Repositories

If you need to access private repositories in an organization:

1. Make the app public: In app settings → Advanced → Make public
   • Public apps can be installed on any account
   • Private apps can only be installed on the owning account
2. Install on the organization: Install app → Select your organization
3. Organization admin approval: An org owner must approve the installation
4. User authorization: Each user must authorize the app when they first use it

Understanding GitHub App Authorization Flow

GitHub Apps use a two-step process that separates installation from authorization:

1. Installation (One-time, Admin Action)

Who: Repository admin or organization owner What: Installs the app on specific repositories Grants: App can access those repositories’ data

This happens once when setting up the app. Installation guide 

2. User Authorization (Per-User, First Use)

Who: Each individual user What: Authorizes the app to act on their behalf Grants: App can perform actions as that user

This happens when a user first interacts with your agent/app. Arcade handles this automatically. Authorization guide 

Key Differences

Managing User Authorizations

How Users Revoke Authorization

Users can revoke their authorization to your GitHub App at any time. This is important for user privacy and security.

Steps for Users:

1. Go to GitHub Settings → Applications → Authorized GitHub Apps
2. Find your app in the list
3. Click Revoke next to the app name
4. Confirm the revocation

Direct Link: github.com/settings/apps/authorizations 

How Admins Revoke App Installation

Organization owners and repository admins can remove app installations:

Steps for Admins:

1. Go to Settings → Applications → Installed GitHub Apps
2. Find the app in the list
3. Click Configure next to the app
4. Scroll to the bottom and click Uninstall
5. Confirm the uninstallation

Direct Link: github.com/settings/installations 

Difference: Revoke Authorization vs Uninstall

Best Practices:

• Users should revoke authorization when they stop using your agent
• Admins should uninstall when the app is no longer needed organization-wide
• After permission changes, users should revoke and reauthorize to get updated permissions

Configuring GitHub Auth in Arcade

GitHub Enterprise Server Setup

If your organization uses GitHub Enterprise Server (GHES), you’ll need to create a separate GitHub App and configure a custom OAuth provider in Arcade.

GHES vs GitHub.com: Key Differences

Creating a GitHub App on GHES

Configuring Custom Provider in Arcade

Using Your GHES Provider

When calling Arcade tools or auth methods, specify your custom provider ID:

client = Arcade()
 
auth_response = client.auth.start(
    user_id=user_id,
    provider="my-company-github-enterprise",  # Your custom provider ID
)

const client = new Arcade();
 
let authResponse = await client.auth.start(
  userId,
  "my-company-github-enterprise" // Your custom provider ID
);

GHES Version Compatibility

Rate Limits on GHES

Unlike github.com’s fixed rate limits, GHES administrators can configure custom rate limits for their instance.

If you hit rate limits:

1. Verify your app is properly implementing rate limit headers
2. Contact your GHES administrator about the configured limits
3. Request an increase if needed for your use case

Learn more about GHES rate limit configuration 

Using GitHub Auth in App Code

Use the GitHub auth provider to get a user token for the GitHub API. See authorizing agents with Arcade for details.

Use client.auth.start() to get a user token:

import requests
from arcadepy import Arcade
 
client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
 
user_id = "{arcade_user_id}"
 
"""
In this example, we use Arcade to authenticate with GitHub and retrieve
the number of stargazers of the ArcadeAI/arcade-ai repository.
 
There is a tool for that in the Arcade SDK, which simplifies the process.
Below we're showing how to use Arcade as an auth provider directly.
"""
 
# Start the authorization process
auth_response = client.auth.start(
    user_id=user_id,
    provider="github",
)
 
if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)
 
# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)
 
if not auth_response.context.token:
    raise ValueError("No token found in auth response")
 
token = auth_response.context.token
 
owner = "ArcadeAI"
name = "arcade-ai"
headers = {
    "Accept": "application/vnd.github+json",
    "Authorization": f"Bearer {token}",
    "X-GitHub-Api-Version": "2022-11-28",
}
url = f"https://api.github.com/repos/{owner}/{name}"
 
response = requests.get(url, headers=headers)
response.raise_for_status()
 
print(response.json().get("stargazers_count"))

import { Arcade } from "@arcadeai/arcadejs";
 
const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
 
const userId = "{arcade_user_id}";
 
/*
In this example, we use Arcade to authenticate with GitHub and retrieve
the number of stargazers of the ArcadeAI/arcade-ai repository.
 
There is a tool for that in the Arcade SDK, which simplifies the process.
Below we're showing how to use Arcade as an auth provider directly.
*/
 
// Start the authorization process
let authResponse = await client.auth.start(userId, "github");
 
if (authResponse.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(authResponse.url);
}
 
// Wait for the authorization to complete
authResponse = await client.auth.waitForCompletion(authResponse);
 
if (!authResponse.context.token) {
  throw new Error("No token found in auth response");
}
 
const token = authResponse.context.token;
 
const owner = "ArcadeAI";
const name = "arcade-ai";
const headers = {
  Accept: "application/vnd.github+json",
  Authorization: `Bearer ${token}`,
  "X-GitHub-Api-Version": "2022-11-28",
};
const url = `https://api.github.com/repos/${owner}/${name}`;
 
const response = await fetch(url, { headers });
if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
console.log(data.stargazers_count);

Using GitHub Auth in Custom Tools

Use the pre-built Arcade GitHub MCP Server for quick GitHub integration.

For custom tools, use the GitHub() auth class. The context.authorization.token field will be automatically populated:

from typing import Annotated
 
import httpx
from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import GitHub
 
@tool(requires_auth=GitHub())
async def count_stargazers(
    context: ToolContext,
    owner: Annotated[str, "The owner of the repository"],
    name: Annotated[str, "The name of the repository"],
) -> Annotated[int, "The number of stargazers (stars) for the specified repository"]:
    """Count the number of stargazers (stars) for a GitHub repository."""
    if not context.authorization or not context.authorization.token:
        raise ValueError("No token found in context")
 
    headers = {
        "Accept": "application/vnd.github+json",
        "Authorization": f"Bearer {context.authorization.token}",
        "X-GitHub-Api-Version": "2022-11-28",
    }
    url = f"https://api.github.com/repos/{owner}/{name}"
 
    async with httpx.AsyncClient() as client:
        response = await client.get(url, headers=headers)
        response.raise_for_status()
        return response.json().get("stargazers_count", 0)

Tool Permissions Reference

This section lists the GitHub App permissions required by tools in the Arcade GitHub MCP Server.

Summary Table

Detailed Permissions by Category

Important Gotchas

Permission Changes Require User Reauthorization

When you modify permissions in your GitHub App settings, existing user authorizations don’t automatically receive the new permissions.

What Happens:

1. You update permissions in GitHub App settings
2. Organization admins may need to approve the changes
3. Existing user tokens still have old permissions
4. Users must reauthorize to get new permissions

Solution:

• Users should revoke their authorization in Arcade and reauthorize
• Or, admins can revoke all authorizations in GitHub App settings
• New users will automatically get the updated permissions

Learn more about permission updates 

404 Errors Can Mean Missing Permissions or Installation

GitHub returns 404 Not Found (not 403 Forbidden) in several scenarios:

Possible Causes:

1. App not installed on the target repository
2. Permissions not approved by organization admin
3. Repository doesn’t exist or you lack access
4. User hasn’t authorized the app yet

Why 404 Instead of 403? GitHub doesn’t reveal which repositories exist when you lack access (security by obscurity).

Solution:

1. Verify the app is installed on the target repository
2. Check that all required permissions are approved
3. Ensure the user has authorized the app
4. Confirm the repository path is correct

Installing on Additional Repositories

After initial installation, you can add more repositories:

Via GitHub Settings:

1. Go to Settings → Applications → Installed GitHub Apps
2. Click on your app name
3. Click Configure
4. Under “Repository access”, click Select repositories
5. Choose additional repositories
6. Click Save

Official guide for managing installations 

Permissions ≠ Scopes

• GitHub Apps use permissions (fine-grained), not scopes (OAuth Apps)
• Scopes aren’t present in GitHub App tokens
• User is still limited by their own GitHub permissions (can’t elevate privileges)

Personal vs Organization GitHub Apps

Functionally the same, but:

• Personal account app: You own and manage it
• Organization app: Org owns it, can be managed by org admins
• Both can be installed on any account if “Any account” is selected

Troubleshooting

Common Errors

Debugging Steps

1. Verify Installation

   • Go to Settings → Applications → Installed GitHub Apps
   • Confirm app is installed on target repository
   • Review your installations 

2. Check User Authorization

   • Verify the user has authorized the app
   • Users can check at: Settings → Applications → Authorized GitHub Apps
   • If not authorized, user needs to use your agent/app to trigger authorization flow

3. Check Permissions

   • Review app settings → Permissions & events
   • Ensure all required permissions are granted
   • Verify organization approval (if applicable)
   • After changing permissions: Users must reauthorize

4. Test Credentials

   • Verify Client ID and Client Secret are correct in Arcade dashboard
   • Ensure redirect URL in GitHub matches Arcade’s generated URL
   • Check that “Request user authorization (OAuth) during installation” is enabled

Frequently Asked Questions

General

Q: Is GitHub Apps free? A: Yes! Free GitHub accounts support GitHub Apps. No paid plan needed.

Q: Can I use one app for multiple projects? A: Yes! Install the same app on multiple repositories. Each gets a unique Installation ID.

Q: What if I lose my private key? A: Generate a new one from app settings. The old key will be invalidated. You cannot recover lost keys.

Installation

Q: Do I need to be an org owner? A: To create an app: No (any user can create). To install on org: Yes (or need owner approval). Organization owners control which apps can be installed. Learn more 

Q: How do I install the app on additional repositories? A: Settings → Applications → Installed GitHub Apps → Click your app → Configure → Select additional repositories.

Q: Can I change permissions later? A: Yes, anytime. After changing:

• Organization installs require admin approval for new permissions
• Users must reauthorize for new permissions to take effect
• Best practice: Users should revoke old authorization and reauthorize
• Guide to updating permissions 

Usage

Q: Which tools need org permissions? A: Project management, collaborators listing, org repo listing, and user search within org context.

Q: What’s the rate limit? A: GitHub Apps: 5,000/hour per installation + 12,500/hour for user endpoints. OAuth: 5,000/hour total.

Q: Can I use with GitHub Enterprise Server? A: Yes! See the GitHub Enterprise Server Setup section above. You’ll need to create a custom provider with your GHES instance URLs.

Q: Why can’t I star repositories? A: Starring repositories requires the “Act on behalf of user” permission:

• Enable “Act on behalf of user” in User permissions section
• This permission makes actions appear as the user (not the app)
• Users must authorize this permission when they first use your agent
• The app can still read and perform other actions without this permission
• Why this permission exists 

Q: Why can’t I access notifications? A: Notifications require a classic PAT (GitHub Apps cannot access notifications API by design):

• This is a platform limitation, not an Arcade limitation
• Create a classic PAT at github.com/settings/tokens  with notifications scope
• Why GitHub Apps can’t access notifications 

Security

Q: What if my credentials are compromised? A: Immediately take these steps:

1. Revoke the Client Secret in GitHub App settings
2. Generate a new Client Secret
3. Update your Arcade OAuth provider configuration
4. Review GitHub audit logs for suspicious activity
5. Consider revoking all user authorizations
6. Notify affected users if necessary

GitHub security best practices 

Q: Why can’t the app access all my repositories? A: Security by design. Apps only access repositories they’re explicitly installed on. This limits blast radius if compromised.

GitHub Enterprise Server

Q: Can I use the same GitHub App for github.com and GHES? A: No. GitHub Apps created on github.com cannot be installed on GHES instances, and vice versa. Each GHES instance requires its own separate GitHub App registration. This is a GitHub platform limitation, not an Arcade limitation.

Q: Can I use the same app configuration for multiple GHES instances? A: Yes! You can share the same manifest or URL parameters with multiple GHES instances. Each instance will register their own GitHub App with identical settings, but you’ll need to create separate custom providers in Arcade for each instance.

Q: Does GHES support all the same features as github.com? A: Not always. GHES may have feature differences and typically receives new API endpoints, GraphQL objects, and webhooks later than github.com. Check the x-github-enterprise-version header in API responses to identify the GHES version. Learn more about GHES version differences 

Q: How do I know what GHES version my instance is running? A: Contact your GHES administrator, or check the API response headers which include x-github-enterprise-version. You can also see the version in the GHES footer when logged in.

Q: Can I use the “Included Provider” for GHES? A: No. The included GitHub provider in Arcade is configured for github.com only. You must create a custom provider with your GHES instance URLs. See the GHES setup guide above.

Q: Do GHES rate limits work the same as github.com? A: No. GHES administrators can configure custom rate limits for their instance. If you’re hitting rate limits, contact your GHES admin about the configured limits and request an increase if needed.

Configuration Checklist

Use this checklist to ensure proper setup:

• Created GitHub App (not OAuth App)
• Set all required permissions (Contents, Issues, Pull requests, etc.)
• Enabled “Request user authorization (OAuth) during installation” ✅
• Enabled “Act on behalf of user” for user-level actions
• Generated and securely stored Client Secret
• Noted Client ID
• Installed app on target repositories (or made public for any account)
• Added Arcade redirect URL to GitHub app callback URL
• Configured OAuth provider in Arcade dashboard
• Tested with a simple tool call
• Generated private key (Not needed for Arcade)
• Noted Installation ID (Not needed for Arcade)

For GitHub Enterprise Server:

• Created Custom Provider in Arcade (NOT included provider)
• Configured all endpoint URLs with correct GHES hostname
• Set Authorization endpoint: https://{your-ghes-host}/login/oauth/authorize
• Set Token endpoint: https://{your-ghes-host}/login/oauth/access_token
• Set User Info endpoint: https://{your-ghes-host}/api/v3/user
• Set Refresh Token endpoint (same as Token endpoint)
• Enabled Token Introspection with correct settings:
  • Introspection endpoint: https://{your-ghes-host}/api/v3/user
  • Authentication Method: Bearer Access Token
  • Content-Type: application/json
  • Triggers: OnTokenGrant and OnTokenRefresh enabled
• Tested with GHES-specific provider ID in auth calls
• Verified GHES version compatibility with required features

Additional Resources

Official GitHub Documentation

• GitHub Apps Overview 
• Installing Your Own GitHub App 
• Installing a GitHub App from a Third Party 
• Authorizing GitHub Apps 
• Reviewing and Revoking Authorization 
• Approving Updated Permissions 
• GitHub API Documentation 
• Security Best Practices 

Arcade Resources

• Arcade GitHub MCP Server
• Arcade Authorization Guide
• Video Tutorial: GitHub App Setup 

💡 Remember: Always use GitHub Apps (not OAuth Apps), enable user authorization during installation, and store credentials securely!