Connect GitHub Enterprise Server to Coolhand

Before you start#

You need:

• An organization on your GitHub Enterprise Server instance that contains the repositories you want Coolhand to work on.
• Permission to create a personal access token and an organization webhook in that organization.
• An instance URL that starts with https:// and that Coolhand can reach from the internet. Coolhand cannot connect to an instance that is only reachable on a private network, so put it behind a publicly reachable address or gateway first.

GitHub Enterprise Server is self-hosted, so Coolhand connects with a personal access token instead of the GitHub App used for github.com.

Step 1: Create a personal access token#

Pull requests that Coolhand opens are authored by the token's owner. Create the token from a dedicated service account rather than a personal one, and make sure that account is a member of the organization with write access to the repositories you want to include.

1. Sign in to your GitHub Enterprise Server instance as that account.
2. Go to Settings → Developer settings → Personal access tokens.
3. Generate a new token. A classic token is recommended.
4. Select these scopes:
   • repo: read and write access to repository contents and pull requests.
   • read:org: list the organization's repositories and verify membership.
5. Set an expiry date and note it. An expired token is the most common cause of a failed connection.
6. If your organization enforces SAML single sign-on, open Configure SSO next to the token and authorize it for the organization.
7. Copy the token now. GitHub only shows it once.

If you prefer a fine-grained token, scope it to the organization's repositories with Contents and Pull requests set to read and write and Metadata set to read. Fine-grained token support depends on your GitHub Enterprise Server version, so use a classic token if you are unsure.

Step 2: Connect in Coolhand#

1. In Coolhand, open Settings and find the GitHub Enterprise Integration card.
2. Enter:
   • GitHub Enterprise Instance URL: the base URL only, for example https://github.example.com.
   • GitHub Enterprise Organization: the organization name from a repository URL. For https://github.example.com/my-org/my-repo this is my-org. It is case-sensitive.
   • Personal Access Token: the token from Step 1.
3. Select Connect GitHub Enterprise.

Coolhand tests the connection before saving: it checks that the token is valid, that the organization exists, and that the token can list its repositories. When the test passes, Coolhand shows a webhook URL and a signing secret. Copy both for the next step.

Step 3: Add an organization webhook#

Webhooks tell Coolhand when something changes on your instance. Create the webhook on the organization, not on a single repository. A repository-level webhook cannot report new or deleted repositories.

1. In GitHub Enterprise Server, open your organization and go to Settings → Webhooks → Add webhook.
2. Set:
   • Payload URL: the webhook URL from Coolhand.
   • Content type: application/json.
   • Secret: the signing secret from Coolhand. This is a separate value from the URL.
3. Under Which events would you like to trigger this webhook?, choose Let me select individual events and check:
   • Repositories
   • Pushes
   • Pull requests
   • Pull request reviews
   • Pull request review comments
   • Pull request review threads
   • Issue comments
   • Issues
   • Commit comments
   • Branch or tag creation
   • Check runs
   • Workflow runs
4. Select Add webhook.
5. Open the webhook's Recent Deliveries tab and confirm Coolhand responded with 200 OK.

Today, Coolhand uses Repositories events to keep your repository list current when a repository is created, deleted, renamed, transferred, archived, unarchived, made private or public, or has its default branch changed. The other events are received and verified but not yet acted on. Subscribing to them now means you will not need to change the webhook when Coolhand starts using them. If you would rather keep delivery volume down on a busy organization, subscribe to Repositories only.

What Coolhand does with the connection#

• Lists and keeps in sync the repositories in your organization.
• Clones repositories so the coding agent can work on them.
• Opens, updates and closes pull requests on your instance.
• Links an existing pull request from your instance to a change suggestion.

Coolhand does not yet respond automatically to pull request review comments or track CI check runs on GitHub Enterprise Server, as it does on github.com.

Troubleshooting#

"Invalid token": the token has expired, was copied incorrectly, or is missing the repo or read:org scope. Create a new token and reconnect.

"Insufficient permissions": the token is valid but cannot list the organization's repositories. Check the scopes, and check that the token is authorized for SAML single sign-on if your organization requires it.

"Organization not found": the organization name must match exactly, including case, and the token's owner must be able to see the organization.

"Could not connect to GitHub Enterprise with the supplied details": the instance URL is wrong, uses http://, or cannot be reached from Coolhand. Check that the URL is the base URL only, with no path, query string or credentials, and that it resolves to a publicly reachable address.

Webhook deliveries are failing or not arriving: open Recent Deliveries on the webhook and read the response. Confirm the payload URL and secret match what Coolhand shows, and that your instance's outbound webhook rules allow it to reach Coolhand.

Repositories are missing from Coolhand: the token's owner may not have access to them. Add the account to the repositories or their team, then wait for the next repository event or reconnect to trigger a sync.