GitHub auth provider

The GitHub auth provider enables tools and agents to call GitHub APIs (opens in a new tab) on behalf of a user. Behind the scenes, the Arcade Engine and the GitHub auth provider seamlessly manage GitHub OAuth 2.0 authorization for your users.

What's documented here

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

This auth provider is used by:

• The Arcade GitHub toolkit, 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

Configuring GitHub auth

How you configure the GitHub auth provider depends on whether you use the Arcade Cloud Engine or a self-hosted Engine.

With the Arcade Cloud Engine, you can start building and testing GitHub auth without any configuration. Your users will see Arcade AI (demo) as the name of the application that's requesting permission.

When you are ready to go to production, you'll want to configure the GitHub auth provider with your own GitHub app credentials, so users see your app name when they authorize access.

Create a GitHub app

• Follow GitHub's guide to registering a GitHub app (opens in a new tab)
• Choose the permissions you need for your app
• Set the redirect URL to: https://cloud.arcade-ai.com/api/v1/oauth/callback
• Copy the client ID and client secret

Configuring GitHub auth with the Arcade Cloud Engine

Configuring GitHub auth with a self-hosted Arcade Engine

export GITHUB_CLIENT_ID="<your client ID>"
export GITHUB_CLIENT_SECRET="<your client secret>"

GITHUB_CLIENT_ID="<your client ID>"
GITHUB_CLIENT_SECRET="<your client secret>"

auth:
  providers:
    - id: github
      client_id: ${env:GITHUB_CLIENT_ID}
      client_secret: ${env:GITHUB_CLIENT_SECRET}

Using GitHub auth in app code

Use the GitHub auth provider in your own agents and AI apps to get a user token for the GitHub API. See authorizing agents with Arcade to understand how this works.

Use client.auth.start() to get a user token for the GitHub API:

from arcadepy import Arcade
 
client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
 
user_id = "[email protected]"
 
# 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.authorization_url)
 
# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)
 
token = auth_response.context.token
# TODO: Do something interesting with the token...

Using GitHub auth in custom tools

The Arcade LLM API is a convenient way to call LLMs and automatically invoke tools. You can use the pre-built Arcade GitHub toolkit to quickly build agents and AI apps that interact with GitHub.

If the pre-built tools in the GitHub toolkit don't meet your needs, you can author your own custom tools that interact with the GitHub API.

Use the GitHub() auth class to specify that a tool requires authorization with GitHub. The context.authorization.token field will be automatically populated with the user's GitHub token:

from typing import Annotated
 
from arcade.sdk import ToolContext, tool
from arcade.sdk.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."""
 
    token = context.authorization.token
    # TODO: Call the GitHub API with this token!