# Configure GitHub

Let an agent query repositories, issues, and pull requests, or receive GitHub events. Start with a read-only query.

## Prepare a token

Confirm the target repositories with their owner. Use a personal access token restricted to those repositories and the permissions needed for the task, with an expiry date. Organization approval may be required.

You need permission to create or edit tool configuration in the current MOI workspace. If the entry is missing or access is denied, contact the workspace administrator rather than using another person's account.

### Create a fine-grained personal access token

1. Open [Create a fine-grained token](https://github.com/settings/personal-access-tokens/new), or navigate through **Settings → Developer settings → Personal access tokens → Fine-grained tokens**.
2. Select **Generate new token**, enter a name, and set an expiry.
3. Under **Repository access**, select **Only select repositories** and choose the intended repositories.
4. Set repository permissions for the agent's operations. Use read-only access for reading repository content, issues, or pull requests. Set **Issues → Read and write** only when creating or updating issues is needed.
5. Generate and immediately copy the token; GitHub does not show the complete value again.

GitHub also provides **Tokens (classic)**, but fine-grained tokens allow this setup to be restricted by repository and action. For organization repositories, wait for required administrator approval before testing access.

## Configure MOI

1. Open **Resource Center → Tools → GitHub**, select repository API access, and create an instance.
2. Enter the Access Token and, to identify the test scope, Owner and Repository. Save and test.
3. Bind the GitHub capability and select this instance in agent details. Validate a read-only task first.
4. If event triggers are needed, create a Webhook instance. Enter the required fields and matching Webhook Secret, save, and copy the callback URL from instance details.
5. In the repository or organization's Webhooks settings, enter the callback URL and the same secret, then choose the required events. The callback must be reachable by GitHub; `127.0.0.1` is not a third-party callback address.
6. In MOI, configure the event-routing rule and target agent or task. Test with an event from the test repository. For PR review scenarios, subscribe to Check suites, Check runs, or other events requested by the page.

| Scenario | GitHub events |
| --- | --- |
| Issue creation, editing, or closure | Issues |
| Pull request creation, update, or closure | Pull requests |
| PR comments or reviews | Issue comments, Pull request reviews, Pull request review comments |
| Process a PR after CI checks | Check suites, Check runs |

GitHub signs deliveries using the Webhook Secret in `X-Hub-Signature-256`. MOI verifies with the same secret; both values must match. See [Webhook signature validation](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries).

## Fields

| Field | Requirement | Value |
| --- | --- | --- |
| Instance name | Required | A name such as “Product test repository” |
| Access Token | Required for both API and Webhook entries | API credentials; a Webhook Secret cannot replace them |
| Owner / Repository | Optional | Separate values such as `example-team` and `demo`, not a full URL |
| App ID / Installation ID | Optional in API entry | Use only for an actual GitHub App setup; IDs alone do not replace the token |
| Webhook Secret | Optional in Webhook entry | The same secret as in GitHub, used for signature verification rather than API access |

## Validate agent use

After saving, reopen the configuration to confirm it persists and run **Test connection**. Then [bind the capability to the target agent](../bind-tools.md), selecting the intended connection wherever an instance selector is provided. Inspect an actual tool call and compare its result with the target platform. A configured badge or a plausible answer alone is insufficient.

Ask: “Read the three most recent issues in example-team/demo. Only query; do not add comments.” Replace the example with the test repository and compare issue links and tool results.

For events, additionally inspect GitHub's delivery record, MOI reception, and execution by the correct target. Connection testing does not validate event delivery.

## Troubleshoot

| Symptom | Check |
| --- | --- |
| Connected but repository unavailable | Token repository scope, organization approval, and Owner/Repository |
| Reads work but writes fail | Permissions for that specific operation; add write permissions only when needed |
| Webhook does not trigger | Public callback reachability, matching secret, subscriptions, delivery records, and MOI routing |

- [GitHub personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
- [All tool configuration guides](index.md)