Skip to main content

Connect GitHub to Coolhand

Last updated 5 min read

Connect github.com to Coolhand by installing the Coolhand Labs GitHub App on your account or organization, choosing which repositories it can reach, and confirming the connection in Coolhand. This guide covers the install, each permission the app asks for and why, how to change repository access later, and fixes for common problems.

Before you start

You need:

  • A GitHub account, or a GitHub organization you own. To install an app on an organization you must be an owner. If you are not, GitHub sends a request to an owner to approve the install.
  • A Coolhand account. You can create one during the install if you do not have one yet.

Using GitHub Enterprise Server instead? See Connect GitHub Enterprise Server to Coolhand.

Step 1: Install the GitHub App

  1. In Coolhand, open Settings, find the GitHub Integration card, and select Install App. You can also go straight to the Coolhand Labs app on GitHub.
  2. Choose the account or organization to install it on.
  3. Choose which repositories Coolhand can reach: All repositories, or Only select repositories. Coolhand can only see the repositories you choose here.
  4. Review the permissions listed below, then select Install.

Step 2: Confirm the connection in Coolhand

  1. GitHub sends you back to Coolhand. Sign in, or create an account.
  2. Select Connect GitHub Installation to link the installation to your Coolhand workspace.
  3. Coolhand finishes the connection in the background. The GitHub Integration card on the Settings page shows "Connection is being processed" and then "Connected to organization" followed by your organization name.

If the connection cannot be completed, Coolhand emails the people on your team and the Settings page goes back to showing Install App. Run the install again.

Permissions the app asks for

Permission Access What Coolhand uses it for
Metadata Read Finding your repositories. GitHub requires this for every app.
Contents Read and write Reading your code, creating a branch and pushing a fix to it.
Pull requests Read and write Opening pull requests, and reading and replying to reviews and comments on them.
Checks Read Reading the results of your CI checks on a pull request Coolhand opened.
Actions Read and write Following workflow runs, and canceling a CI run on a Coolhand pull request that has stopped making progress.
Issues Read and write Opening a GitHub issue for an optimization Coolhand proposes, when your automatic routing rules say to, and reading comments on issues.

The app asks for no account-level or organization-level permissions, and it cannot see repositories you did not select. Coolhand subscribes to GitHub events for pull requests, reviews, comments, issues, check runs and workflow runs so it can follow its own pull requests.

Comments only steer the coding agent when they come from someone with write access, or higher, to that repository. Comments from anyone else are ignored.

What Coolhand does with the connection

  • Lists the repositories the app can reach, on the Repositories page.
  • Opens pull requests with fixes in your repositories.
  • Follows each pull request it opened: reviews, comments and CI results.

Change which repositories Coolhand can reach

  1. In Coolhand, open Settings, find the GitHub Integration card, and select Manage App. This opens the installation's settings on GitHub.
  2. Change the repository access, or uninstall the app, on GitHub.
  3. To make Coolhand look for newly added repositories, open the Repositories page and select Scan All Repos.

If Coolhand's permissions change in the future, GitHub emails the organization owners and Coolhand shows a banner saying "GitHub App permissions need updating". Use the link in the banner to review and accept the new permissions on GitHub. Until you do, actions that need the new permission will not work.

Troubleshooting

The Settings page still shows "Install App" after installing: the connection did not finish. Run the install again and make sure you select Connect GitHub Installation when GitHub sends you back to Coolhand.

The Settings page shows the wrong organization: the app is installed on a different account than you meant. Uninstall it from the wrong account on GitHub, then install it on the right one.

A repository is missing from Coolhand: the app was not given access to it. Add it with Manage App, then select Scan All Repos on the Repositories page.

Coolhand says its GitHub permissions need updating: accept the new permissions from the link in the banner. You may need to ask an organization owner to do it.

You are not an organization owner: GitHub sends the install request to an owner. The connection starts once they approve it.

Related articles