GitHub Integration

The GitHub integration connects Cotool to repositories through a 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. You can connect with the Cotool-managed GitHub App, with a GitHub App you own (bring your own App), or both. The most common reason to bring your own App is to enforce read-only access: you register an App with only read permissions, and GitHub — not Cotool — rejects any write on every request made through it. Agents can still investigate code and pull requests in those repositories, but cannot commit, open pull requests, or change workflows there, no matter what they are asked to do. Pair it with the managed App on your other repositories to keep full pull-request workflows where you want them.

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 — including as drafts — 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.

Bring your own GitHub App

Connect a GitHub App you register and own, so your organization chooses the permissions Cotool is granted — including read-only.

Choosing How to Connect

	Cotool-managed App	Bring your own App
Who owns the App	Cotool	Your GitHub organization
Permissions	Fixed by Cotool; supports the full set of agent GitHub tools	Chosen by you when you create the App; GitHub enforces them on every Cotool request
Setup	Click Connect and install	Create a GitHub App, paste its credentials into Cotool, then install it
Typical use	Default; fastest path	Read-only access to sensitive repos, or stricter permission review requirements

Either App can be installed on multiple GitHub organizations, and both Apps can be connected to the same Cotool organization at once — even on the same GitHub organization, as long as each repository is selected for only one of them. See Installing across GitHub organizations and Using both Apps together.

Setup with the Cotool-managed App

Open the GitHub integration

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

Install the GitHub App

Under Cotool-managed GitHub App, click Connect. GitHub will ask you to install the Cotool GitHub App on an organization or user account. For a GitHub organization, an organization owner must complete the installation.

Choose repository access

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

Authorize your GitHub user

After installing the app, authorize Cotool as a GitHub user who can access the new installation. Cotool verifies this access before linking the installation to your Cotool organization.

Finish the connection

After authorization, GitHub returns you to Cotool. The GitHub integration page will show the connection state and any feature cards that depend on GitHub.

Cotool does not support GitHub’s pending installation-request flow. If GitHub offers Request instead of Install, ask an organization owner to open the GitHub integration in Cotool and complete the connection.

You need permission to install GitHub Apps in the target GitHub organization. In Cotool, connecting GitHub and configuring GitHub-dependent sync settings require the tool.manage permission.

Setup with Your Own GitHub App

Use this when your organization wants to control the permissions Cotool is granted. You create the App in GitHub, give Cotool its credentials, then install it on your organization the same way as the managed App.

Open the custom App setup

In Settings > Integrations > GitHub, find Bring your own GitHub App and click Set up custom App. The dialog shows the exact values to paste into GitHub’s Create GitHub App form.

Create the App in GitHub

In your GitHub organization, go to Settings > Developer settings > GitHub Apps > New GitHub App and fill in the form using the values from the Cotool dialog:

Identifying and authorizing users — add Cotool’s callback URL as a Redirect URI. Leave Request user authorization (OAuth) during installation unchecked.
Post installation — use the same callback URL as the Setup URL. Leave Redirect on update unchecked.
Webhook — GitHub requires a Webhook URL before it will create the App. Paste the Cotool-provided URL now, leave Active unchecked and Secret blank for the moment.
Permissions — choose what Cotool may do. See Permissions below.

Paste the App's credentials into Cotool

After GitHub creates the App, copy its App ID and Client ID, generate a client secret, and generate and download a private key. Paste all four into the Cotool dialog and save. Cotool verifies the credentials against GitHub — the App ID, private key, and client ID must all belong to the same App, and the required Members permission must be present — before storing anything.

Finish the webhook

Once Cotool shows Credentials verified, it displays a Cotool-generated webhook secret. Back in GitHub’s App settings, paste that secret into the Webhook section, turn Active on, and subscribe to the Installation, Installation target, and Installation repositories events. These let Cotool keep repository routing current as you change the App’s repository access.

Install the App

Click Add organization under Bring your own GitHub App. GitHub walks you through installing your App on an organization and choosing repositories, then Cotool verifies your GitHub user and links the installation — exactly as with the managed App.

Permissions on your own App

GitHub enforces your App’s permissions on every request Cotool makes, so choose them to match what you want agents to be able to do:

Cotool capability	GitHub permission required
Read files, commits, blame, branch rules, repository metadata	Contents: Read (and Metadata, which GitHub always grants)
Read and list pull requests	Pull requests: Read
Commit files to a branch	Contents: Read and write
Open, update, or close pull requests; request reviewers	Contents: Read and write and Pull requests: Read and write
Create or update GitHub Actions workflow files	additionally Workflows: Read and write
Complete setup (verify the installer is an organization owner)	Organization → Members: Read — required

Organization → Members: Read is the one permission Cotool requires on a bring-your-own App. Cotool uses it during setup to confirm that the person connecting the installation is an owner of the GitHub organization. Without it, the installation cannot be linked and Cotool reports that a GitHub organization owner must approve the App’s permission update before retrying.

Recipe: a read-only App

To guarantee agents can never modify a set of repositories, create your App with exactly:

Repository → Contents: Read
Repository → Pull requests: Read
Organization → Members: Read (required for setup)

and leave every other permission at No access. Install it on the repositories you want protected. Agents can read files, history, blame, branch rules, and pull requests there, but every commit, pull-request, or workflow write is refused by GitHub itself, so the guarantee does not depend on Cotool’s behaviour or on how an agent is prompted. Cotool’s write tools remain visible to agents, and github_listRepositories reports these repositories as read-only with every write capability false, so agents know not to attempt them — see What agents can see. If you change the App’s permissions later, GitHub asks an organization owner to approve the new permissions for each existing installation. Cotool picks up the approved permissions on its next request; no reconnect is needed.

Managing your App

Manage App under Bring your own GitHub App lets you update the App’s credentials, rotate the Cotool-generated webhook secret, or remove the App configuration. Switching to a different App ID or removing the configuration is blocked while any of its installations are still connected — disconnect those first.

Installing Across GitHub Organizations

A single GitHub App — managed or your own — can be installed on as many GitHub organizations (or user accounts) as you need, and Cotool treats each installation as a separate connection. Click Connect / Add organization again to install the same App on another organization. The integration page groups your installations by GitHub organization.

Using Both Apps Together

Your Cotool organization can have the managed App and your own App connected at the same time, and the two Apps may be installed on different GitHub organizations or on the same one. Every repository is served by exactly one installation, so Cotool routes each repository as follows:

A repository visible to only one installation is routed through that installation.
Two Apps may share a GitHub organization as long as they are installed on disjoint sets of repositories — each repository selected for one App and not the other. This is how you run a read-only App on sensitive repositories and the managed App on everything else within a single GitHub organization.
If you install a second App on an organization and its selected repositories overlap an existing Cotool installation, the new installation is rejected and Cotool shows the exact overlapping repositories. If an already-connected installation later gains a repository that another installation already serves, that whole installation is marked Blocked — none of its repositories are used — until the overlap is resolved.
To resolve an overlap, change the repository selection on one App in GitHub so each repository is selected for only one App. Cotool reconciles automatically via the installation webhooks and unblocks the installation; rejected installations are retried without any action in Cotool.

The integration page groups installations by GitHub organization and shows which App serves each, along with any blocked state and links to each App’s repository settings in GitHub.

What Agents Can See About Their Access

When an agent lists repositories (github_listRepositories / github_searchRepositories), each repository includes a cotool_access block describing the App and installation that serve it and what Cotool is permitted to do there, based on the permissions GitHub actually granted that installation:

{
    "full_name": "acme/payments",
    "cotool_access": {
        "app_slug": "acme-cotool-readonly",
        "app_source": "customer",
        "installation_id": "12345678",
        "level": "read-only",
        "can": {
            "read": true,
            "commit": false,
            "open_pull_request": false,
            "edit_workflows": false,
            "request_reviewers": false
        },
        "granted_permissions": {
            "contents": "read",
            "pull_requests": "read",
            "members": "read",
            "metadata": "read"
        }
    }
}

The response also lists every connected App under apps, with the permissions granted to each of its installations. Agents use this to answer questions like “which repositories are you read-only on?” directly, and to check before attempting a write that the serving App allows it.

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 a connected GitHub App (managed or your own) is installed on the organization or user account that owns the repo.
Confirm that installation has access to that specific repository.
Check the integration page for a Blocked installation — a repository selected for both Apps disables the affected installation until the overlap is removed.
Reconnect or update the GitHub App installation if repository access changed after the original setup.

The same installations are 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. If a write tool fails with a permissions error on a repository served by your own App, check that App’s permissions in GitHub — Cotool cannot exceed what the App was granted.

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:

Select a repository

Choose from repositories available to the GitHub App installation.

Select a branch

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

Select a path

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

Enable and save sync

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

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.

Changing your own App’s permissions or repository selection in GitHub does not require reconnecting; Cotool picks up the change on its next request or webhook.

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

Triggering Agents — configure agent triggers in the UI or YAML

Getting Started

Core Concepts

Chat

Agents

Triage

Hunt

Detections

Improving Agents

Settings

Integrations

Features

Repository access

Pull request workflows

Response Agents as Code

Scoped installation

Bring your own GitHub App

Choosing How to Connect

Setup with the Cotool-managed App

Setup with Your Own GitHub App

Permissions on your own App

Recipe: a read-only App

Managing your App

Installing Across GitHub Organizations

Using Both Apps Together

What Agents Can See About Their Access

Repository Access

Response Agents as Code Sync

Disconnecting or Reconnecting

​Features

Repository access

Pull request workflows

Response Agents as Code

Scoped installation

Bring your own GitHub App

​Choosing How to Connect

​Setup with the Cotool-managed App

​Setup with Your Own GitHub App

​Permissions on your own App

​Recipe: a read-only App

​Managing your App

​Installing Across GitHub Organizations

​Using Both Apps Together

​What Agents Can See About Their Access

​Repository Access

​Response Agents as Code Sync

​Disconnecting or Reconnecting

​Related

Features

Choosing How to Connect

Setup with the Cotool-managed App

Setup with Your Own GitHub App

Permissions on your own App

Recipe: a read-only App

Managing your App

Installing Across GitHub Organizations

Using Both Apps Together

What Agents Can See About Their Access

Repository Access

Response Agents as Code Sync

Disconnecting or Reconnecting

Related