# GitHub

Connect GitHub and use its tools through the Authlane control plane.

## Prerequisites

Create a GitHub OAuth app and choose an account that can access the repositories your tools will
read or change. Repository and organization policy can still restrict that account after consent.
Use GitHub's [REST documentation](https://docs.github.com/en/rest),
[OAuth app guide](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app),
and [developer settings](https://github.com/settings/developers) as the source of truth.

## Self-hosted setup

1. In GitHub developer settings, choose **OAuth Apps → New OAuth App**.
2. Set the homepage to your product and the callback to
   `https://<your-authlane-host>/api/v1/oauth/github/callback`.
3. Save the app, copy the Client ID, and generate a Client Secret.
4. Review organization OAuth restrictions before testing a private repository.

## Configure authentication

Open **Dashboard → Services → GitHub → OAuth Configuration**, enter the Client ID and Client Secret,
save, and enable GitHub. Authlane encrypts the secret. The callback must match exactly, including
scheme, host, and path.

## Scopes

- `repo` permits repository, issue, pull-request, code, and file operations.
- `user` reads the authorizing user's account context used by repository discovery.

## Execution path

Every GitHub tool runs against GitHub's own MCP server at `https://api.githubcopilot.com/mcp/`;
follow the [official MCP setup](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/set-up-the-github-mcp-server).
Authlane ships no direct-API handlers for GitHub, so there is no second path: the tools listed below
are the ones Authlane reviewed, and the server offers many more that arrive through discovery.

**A connection whose token that server refuses has no working GitHub tool.** The endpoint expects a
token with Copilot access, and Authlane used to paper over a refusal by calling `api.github.com`
instead — which quietly limited every workspace to eight hand-written operations. Losing the
workaround is the price of the full surface; the failure now names itself as
`PROVIDER_MCP_TOOL_UNAVAILABLE` rather than silently doing something smaller.

## Available tools

### Discover and read repositories

- `github_list_repos`
- `github_get_file`
- `github_search_code`

### Issues

- `github_list_issues`
- `github_create_issue`

### Pull requests

- `github_list_pull_requests`
- `github_create_pull_request`

### Files

- `github_create_file`

Install `@authlane/integration-github` in the SaaS runtime. Tool callbacks obtain a fresh lease and
the adapter calls GitHub directly; Authlane supplies status and definitions without handling the
provider request or response.

## Connection lifecycle

After GitHub consent, Authlane encrypts the credential and returns `connected`. If GitHub supplies
expiry and refresh material, the background refresh path uses it; otherwise the credential remains
usable until GitHub rejects or revokes it. Reconnect an `expired` or `error` connection. Disconnect
through a fresh hosted session after recent user reauthentication.

## Troubleshooting

- Confirm the exact owner and repository name and that the connected account can see the repo.
- Organization policy or repository permissions can block writes even with the configured `repo`
  scope.
- Updating an existing file with `github_create_file` requires the current file SHA.