> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atollhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub integration

> Connect GitHub repositories, link pull requests to Atoll tasks, and auto-close work from merged PRs.

The GitHub integration connects repository activity back to Atoll tasks.

## What it does

* Lists available repositories for connection.
* Registers webhooks for connected repositories.
* Detects issue identifiers in PR titles or branch names.
* Records PR links on matching Atoll issues.
* Lets you attach a GitHub pull request URL manually when automatic matching misses one.
* Refreshes linked PR metadata, including title, state, head SHA, URL, and repository details.
* Can close tasks when linked pull requests merge.

## Issue identifiers

Use task identifiers in branch names and PR titles:

```text theme={null}
ATOLL-42-fix-login-callback
Fix OAuth callback for ATOLL-42
```

Atoll matches project prefixes and issue numbers, such as `ATOLL-123`.

## API endpoints

| Method | Endpoint                                   | Description                        |
| ------ | ------------------------------------------ | ---------------------------------- |
| `GET`  | `/api/orgs/{id}/github-connections`        | List connected repositories        |
| `GET`  | `/api/integrations/github/repos`           | List available repositories        |
| `POST` | `/api/integrations/github/connect`         | Connect a repository               |
| `POST` | `/api/integrations/github/disconnect`      | Disconnect a repository            |
| `GET`  | `/api/orgs/{id}/issues/{issueId}/pr-links` | List PR links for an issue         |
| `POST` | `/api/orgs/{id}/issues/{issueId}/pr-links` | Attach a GitHub PR URL to an issue |

## Required configuration

The hosted Atoll app manages this for production. For local or self-hosted development, the app expects GitHub OAuth and webhook settings such as:

```bash theme={null}
GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET
GITHUB_WEBHOOK_SECRET
NEXT_PUBLIC_APP_URL
```

<Tip>
  Teach contributors and agents to include the Atoll issue identifier in every branch or PR title. That is the most reliable way to preserve the work trail.
</Tip>