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

# GitHub Integration

> Connect GitHub to Agile Tools for seamless development tracking

# GitHub Integration

Connect your GitHub organization or repositories to Agile Tools.

## Supported Versions

* **GitHub.com** — Full support
* **GitHub Enterprise Server** — Version 3.0+

## Setup Steps

**1. Navigate to Integrations**

Go to **Settings** → **Integrations** → **Source Code Management**

**2. Select GitHub**

Click the **GitHub** card and choose your GitHub edition: - GitHub.com -
GitHub Enterprise Server (provide your server URL)

**3. Authorize Agile Tools**

Click **Connect** to open the GitHub OAuth flow. Sign in and authorize the
Agile Tools application. Required permissions: - `repo` — Access
repositories - `read:org` — Read organization membership - `admin:repo_hook`
— Create webhooks

**4. Select repositories**

Choose which repositories to connect: - **All repositories** — Current and
future repos - **Select repositories** — Pick specific repos

**5. Configure sync settings**

* **Link commits** — Enable/disable commit linking - **Webhook events** —
  Choose which events to receive (push, PR, issues) - **Default Value Unit** —
  Optionally map repos to Value Units

## Verifying the Connection

After setup, verify the integration:

1. Go to **Settings** → **Integrations** → **GitHub**
2. Check the **Status** shows "Connected"
3. View the list of synced repositories
4. Check the **Webhook** status shows recent deliveries

## Linking Commits to Work Items

Once connected, developers can reference Agile Tools items in commit messages:

```
git commit -m "Fix login bug [AT-123]"
```

The `[AT-123]` reference will appear on the corresponding Value Item in Agile Tools.

## Troubleshooting

> **OAuth authorization failed**
>
> Ensure you have Owner or Admin permissions in the GitHub organization.
> Organization owners may need to approve the OAuth app.

> **Webhooks not receiving events**
>
> Check the webhook configuration in GitHub: **Settings** → **Webhooks**. Verify
> the payload URL is correct and the secret matches.

> **Repositories not showing**
>
> The GitHub user who authorized may not have access to all repos. Re-authorize
> with a user who has broader access, or select specific repos.

> [!NOTE]
>
> **Are you a Developer?** Learn how to automate field mappings and customize
> the sync behavior in our [Git Sync
> Automation](https://docs.agile-tools.io/en/developer/integrations/git-sync.md) guide.

## Related

* [SCM Overview](https://docs.agile-tools.io/en/admin/integrations/scm-overview.md) — All SCM integrations
* [GitLab Integration](https://docs.agile-tools.io/en/admin/integrations/gitlab.md)
* [Bitbucket Integration](https://docs.agile-tools.io/en/admin/integrations/bitbucket.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.