GitHub

Overview

Connect your users to GitHub for repository management, issue tracking, pull requests, and code access.

Property	Value
Provider ID	github
Category	Developer Tools
PKCE	Supported
Token refresh	Not needed (tokens don’t expire)
Access token lifetime	Never expires (revoked after 1 year of inactivity)
Redirect URI	Shown in Developer Portal

Note

This guide covers GitHub OAuth Apps, not GitHub Apps. OAuth App tokens don’t expire, so there’s no refresh token flow.

Step 1: Create a GitHub OAuth App

Go to GitHub Developer Settings

Open GitHub Developer Settings, select OAuth Apps, then choose Register a new OAuth application.

For organization-owned apps, go to Organization Settings > Developer settings > OAuth Apps.

Fill in app details

• Application name: The application name (e.g., “My App”)
• Homepage URL: The application’s URL (e.g., https://myapp.com)
• Authorization callback URL: Copy the Redirect URI from the Developer Portal
• Click Register application

Get credentials

After creating the app:

• Client ID: Displayed on the app page
• Client Secret: Click Generate a new client secret and copy it immediately

The Client Secret is only shown once. Store it securely.

Warning

Copy your Client Secret immediately after generating it. GitHub only shows it once.

Step 2: Add to Alter Vault

Open the Developer Portal

Go to portal.alterauth.com and navigate to the application.

Add GitHub provider

Go to OAuth Providers > Add Provider > GitHub.

Enter credentials

• Client ID: Paste your GitHub Client ID
• Client Secret: Paste your GitHub Client Secret

Select scopes

Choose the scopes the application needs. See the Available Scopes section below.

Save

Click Save. The provider is now active.

Step 3: Test It

After a user connects via Alter Connect, use the returned grant_id to make API calls:

from alter_sdk import App, HttpMethod

async with App(
    api_key="alter_key_...",
    caller="my-agent",
) as alter_app:
    response = await alter_app.request(
        HttpMethod.GET,
        "https://api.github.com/user/repos",
        grant_id=grant_id,
        query_params={"sort": "updated", "per_page": "5"},
    )
    repos = response.json()
    for repo in repos:
        print(f"{repo['name']} - {repo.get('description', 'No description')}")

Available Scopes

Repository

Scope	Description
repo	Grants full access to public and private repositories
public_repo	Grants access to public repositories only
repo:status	Grants access to commit statuses without code access
repo_deployment	Grants access to deployment statuses
repo:invite	Grants ability to accept/decline repository invitations
delete_repo	Grants access to delete adminable repositories

User

Scope	Description
user	Grants read/write access to profile info (includes user:email and user:follow)
read:user	Grants read-only access to user profile data
user:email	Grants read access to user’s email addresses
user:follow	Grants access to follow or unfollow other users

Organization

Scope	Description
admin:org	Fully manage organization and its teams, projects, and memberships
write:org	Read and write access to organization membership and projects
read:org	Read-only access to organization membership and team membership

Webhooks & Keys

Scope	Description
admin:repo_hook	Grants full access to repository hooks
admin:org_hook	Grants read, write, ping, and delete access to organization hooks
admin:public_key	Fully manage public keys
admin:gpg_key	Fully manage GPG keys

Other

Scope	Description
gist	Grants write access to gists
notifications	Grants access to user notifications
project	Grants read/write access to user and organization projects
workflow	Grants ability to add and update GitHub Actions workflow files
write:packages	Grants access to upload or publish packages in GitHub Packages
read:packages	Grants access to download packages from GitHub Packages
codespace	Grants ability to create and manage codespaces

Tip

GitHub automatically removes redundant scopes. For example, repo already includes public_repo and repo:status.

Common API Endpoints

Use Case	Method	URL
List user’s repos	GET	https://api.github.com/user/repos
Get a repository	GET	https://api.github.com/repos/{owner}/{repo}
List issues	GET	https://api.github.com/repos/{owner}/{repo}/issues
Create an issue	POST	https://api.github.com/repos/{owner}/{repo}/issues
List pull requests	GET	https://api.github.com/repos/{owner}/{repo}/pulls
Get authenticated user	GET	https://api.github.com/user

Notes

• GitHub OAuth App tokens never expire but are revoked after 1 year of inactivity. There’s no refresh token flow.
• GitHub requires the Accept: application/json header for JSON responses from the token endpoint. Alter Vault handles this automatically.
• If the user’s email is not public, Alter Vault automatically fetches it via the /user/emails endpoint (requires user:email scope).
• GitHub’s API requires the X-GitHub-Api-Version header. When making calls via Alter Vault, you can add it via extra_headers if needed, though most endpoints work without it.
• See the GitHub OAuth authorization documentation for more details.
• See Creating an OAuth app for the provider setup flow.

Policy-cataloged operations

Alter policy rules can target these attested operations and families for operation-level and parameter-aware controls.

Operation ID	Families	Method	Provider path
repos/get	read	GET	/repos/{owner}/{repo}
repos/list-for-authenticated-user	read	GET	/user/repos
repos/create-for-authenticated-user	write	POST	/user/repos
repos/update	admin	PATCH	/repos/{owner}/{repo}
repos/delete	delete	DELETE	/repos/{owner}/{repo}
repos/list-branches	read	GET	/repos/{owner}/{repo}/branches
repos/get-branch	read	GET	/repos/{owner}/{repo}/branches/{branch}
repos/list-commits	read	GET	/repos/{owner}/{repo}/commits
repos/get-commit	read	GET	/repos/{owner}/{repo}/commits/{+ref}
repos/list-releases	read	GET	/repos/{owner}/{repo}/releases
repos/create-release	write	POST	/repos/{owner}/{repo}/releases
repos/create-fork	write	POST	/repos/{owner}/{repo}/forks
repos/list-collaborators	read	GET	/repos/{owner}/{repo}/collaborators
repos/add-collaborator	admin	PUT	/repos/{owner}/{repo}/collaborators/{username}
repos/remove-collaborator	admin	DELETE	/repos/{owner}/{repo}/collaborators/{username}
repos/get-content	read	GET	/repos/{owner}/{repo}/contents/{+path}
repos/create-or-update-file-contents	write	PUT	/repos/{owner}/{repo}/contents/{+path}
repos/delete-file	delete	DELETE	/repos/{owner}/{repo}/contents/{+path}
git/delete-ref	delete	DELETE	/repos/{owner}/{repo}/git/refs/{+ref}
issues/list-for-repo	read	GET	/repos/{owner}/{repo}/issues
issues/get	read	GET	/repos/{owner}/{repo}/issues/{issue_number}
issues/create	write	POST	/repos/{owner}/{repo}/issues
issues/update	write	PATCH	/repos/{owner}/{repo}/issues/{issue_number}
issues/create-comment	write	POST	/repos/{owner}/{repo}/issues/{issue_number}/comments
issues/list-comments	read	GET	/repos/{owner}/{repo}/issues/{issue_number}/comments
pulls/list	read	GET	/repos/{owner}/{repo}/pulls
pulls/get	read	GET	/repos/{owner}/{repo}/pulls/{pull_number}
pulls/create	write	POST	/repos/{owner}/{repo}/pulls
pulls/update	write	PATCH	/repos/{owner}/{repo}/pulls/{pull_number}
pulls/merge	write	PUT	/repos/{owner}/{repo}/pulls/{pull_number}/merge
pulls/create-review	write	POST	/repos/{owner}/{repo}/pulls/{pull_number}/reviews
pulls/list-files	read	GET	/repos/{owner}/{repo}/pulls/{pull_number}/files
actions/list-repo-workflows	read	GET	/repos/{owner}/{repo}/actions/workflows
actions/create-workflow-dispatch	write	POST	/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches
actions/list-workflow-runs-for-repo	read	GET	/repos/{owner}/{repo}/actions/runs
actions/get-workflow-run	read	GET	/repos/{owner}/{repo}/actions/runs/{run_id}
actions/cancel-workflow-run	write	POST	/repos/{owner}/{repo}/actions/runs/{run_id}/cancel
actions/re-run-workflow	write	POST	/repos/{owner}/{repo}/actions/runs/{run_id}/rerun
git/create-ref	write	POST	/repos/{owner}/{repo}/git/refs
search/repos	read	GET	/search/repositories
users/get-authenticated	read	GET	/user