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

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? A: Yes! Works with GitHub Enterprise Server 2.22+. Just set the API URL to your Enterprise instance.

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.

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)

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!