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

# GitHub Integration

> Connect Cotool to GitHub for repository access and Response Agents as Code sync

The GitHub integration connects Cotool to repositories through the Cotool GitHub App. Agents can read repository context, work with pull requests, and, when enabled, sync [Response Agents as Code](/agents/response-agents-as-code) YAML files from a repo into Cotool.

## Features

<CardGroup cols={2}>
  <Card title="Repository access" icon="code">
    Let agents inspect files, commits, blame, pull requests, branch rules, and repository metadata.
  </Card>

  <Card title="Pull request workflows" icon="code-pull-request">
    Allow agents to create, update, review, and close pull requests when their workflow needs to change code.
  </Card>

  <Card title="Response Agents as Code" icon="code-branch">
    Sync response-agent definitions from YAML files in a selected GitHub repo, branch, and folder.
  </Card>

  <Card title="Scoped installation" icon="shield-check">
    Control exactly which GitHub organizations and repositories Cotool can access through the GitHub App installation.
  </Card>
</CardGroup>

## Setup

<Steps>
  <Step title="Open the GitHub integration">
    In Cotool, go to **Settings > Integrations** and open **GitHub**.
  </Step>

  <Step title="Install the GitHub App">
    Click **Connect**. GitHub will ask you to install the Cotool GitHub App on an organization or user account.
  </Step>

  <Step title="Choose repository access">
    Select the repositories Cotool should be able to access. You can grant access to all repositories or only selected repositories.
  </Step>

  <Step title="Finish the connection">
    Return to Cotool after approving the installation. The GitHub integration page will show the connection state and any feature cards that depend on GitHub.
  </Step>
</Steps>

<Note>
  You need permission to install GitHub Apps in the target GitHub organization. In Cotool, configuring GitHub-dependent sync settings requires the `tool.manage` permission.
</Note>

## Repository Access

Cotool uses the GitHub App installation token for the repositories you selected during setup. If a repository does not appear in Cotool:

* Confirm the Cotool GitHub App is installed on the organization or user account that owns the repo.
* Confirm the installation has access to that specific repository.
* Reconnect or update the GitHub App installation if repository access changed after the original setup.

The same installation is used by both agent GitHub tools and the Response Agents as Code sync picker, so the repository, branch, and folder dropdowns only show resources Cotool can actually read.

## Response Agents as Code Sync

After GitHub is connected, the GitHub integration page includes a **Response Agents as Code** card.

Use it to point Cotool at the folder that contains your agent YAML files:

<Steps>
  <Step title="Select a repository">
    Choose from repositories available to the GitHub App installation.
  </Step>

  <Step title="Select a branch">
    Pick the branch Cotool should poll. The picker defaults to the repository's default branch when possible, otherwise `main`.
  </Step>

  <Step title="Select a path">
    Choose the folder containing one-agent-per-file YAML definitions. The default path is `cotool/agents`.
  </Step>

  <Step title="Enable and save sync">
    Turn on **Enable sync** and click **Save config**. Cotool will include your organization in the periodic sync.
  </Step>

  <Step title="Run an immediate sync">
    Click **Sync now** to sync without waiting for the next scheduled poll.
  </Step>
</Steps>

The card shows the latest sync status, the synced commit SHA, and a per-file table. Each row links to the YAML file at the synced commit and shows whether the file synced successfully, failed validation, failed to fetch, or skipped an integration-dependent trigger because the required integration is not connected.

For the YAML format, identity behavior, trigger reconciliation, and rollback model, see [Response Agents as Code](/agents/response-agents-as-code).

## Disconnecting or Reconnecting

If GitHub is disconnected, synced agents keep running with their last synced definition, but Cotool cannot fetch new YAML changes until the integration is reconnected.

Reconnect GitHub when:

* the GitHub App installation was removed,
* repository access changed and Cotool cannot see a repo,
* the Response Agents as Code card shows a reconnect prompt,
* or agent GitHub tools fail because the installation is unavailable.

## Related

<CardGroup cols={2}>
  <Card href="/agents/response-agents-as-code" icon="code-branch">
    **Response Agents as Code** — manage response agents as YAML in GitHub
  </Card>

  <Card href="/agents/triggering-agents" icon="bolt">
    **Triggering Agents** — configure agent triggers in the UI or YAML
  </Card>
</CardGroup>