Skip to main content
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 YAML files from a repo into Cotool.

​
Features

Repository access

Let agents inspect files, commits, blame, pull requests, branch rules, and repository metadata.

Pull request workflows

Allow agents to create, update, review, and close pull requests when their workflow needs to change code.

Response Agents as Code

Sync response-agent definitions from YAML files in a selected GitHub repo, branch, and folder.

Scoped installation

Control exactly which GitHub organizations and repositories Cotool can access through the GitHub App installation.

​
Setup

1

Open the GitHub integration

In Cotool, go to Settings > Integrations and open GitHub.
2

Install the GitHub App

Click Connect. GitHub will ask you to install the Cotool GitHub App on an organization or user account.
3

Choose repository access

Select the repositories Cotool should be able to access. You can grant access to all repositories or only selected repositories.
4

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.
You need permission to install GitHub Apps in the target GitHub organization. In Cotool, configuring GitHub-dependent sync settings requires the tool.manage permission.

​
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:
1

Select a repository

Choose from repositories available to the GitHub App installation.
2

Select a branch

Pick the branch Cotool should poll. The picker defaults to the repository’s default branch when possible, otherwise main.
3

Select a path

Choose the folder containing one-agent-per-file YAML definitions. The default path is cotool/agents.
4

Enable and save sync

Turn on Enable sync and click Save config. Cotool will include your organization in the periodic sync.
5

Run an immediate sync

Click Sync now to sync without waiting for the next scheduled poll.
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.

​
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.

Response Agents as Code — manage response agents as YAML in GitHub

Triggering Agents — configure agent triggers in the UI or YAML