Repos & Access (VCS Connections)

The Repos & Access settings page (Settings → Repos & access) manages the GitHub App connections that Colony uses to interact with your code and the list of repositories Colony is authorized to process.

GitHub App connections

Colony Cloud uses two GitHub Apps. Each connects independently and covers a distinct set of permissions.

App	Type	Permissions
colony-coder	Required	Create branches, push code, open and merge pull requests
colony-operations	Optional	Post review comments, manage issue labels, update issue status

Without colony-coder, Colony cannot perform any code operations. Without colony-operations, Colony still creates PRs and pushes code but cannot post review comments or manage issues under its own identity.

Install colony-coder

1. Open Settings → Repos & access.
2. On the colony-coder card, click Install colony-coder. Colony Cloud redirects you to GitHub’s App installation page.
3. On GitHub, select the organization or account to install the app on, then choose which repositories to grant it access to.
4. Click Install & Authorize. GitHub redirects you back to Colony Cloud, which records the connection automatically.

After the redirect completes, the colony-coder card shows Connected and the Repositories list appears below.

Install colony-operations

colony-operations can only be installed after colony-coder is connected.

1. On the colony-operations card, click Install colony-operations.
2. Complete the GitHub App installation flow as with colony-coder.
3. GitHub redirects back; Colony Cloud records the connection.

Connect another GitHub org

If your Colony Cloud organization spans multiple GitHub organizations, you can connect colony-coder to additional GitHub orgs from the same page.

1. Ensure at least one colony-coder connection is active.
2. Click + Connect another GitHub org below the connection cards.
3. Complete the GitHub installation flow for the additional GitHub organization.

Each connected GitHub org appears as a labeled group in the connections list. The repository list aggregates repos from all connected orgs.

Disconnect an app

1. On the card for the app you want to disconnect, click Disconnect.
2. Confirm the dialog.

colony-coder disconnect: The confirm dialog requires you to type the GitHub organization name before the button becomes active. Disconnecting colony-coder immediately halts all pipeline processing for that org — Workers can no longer create branches or push code until the app is reconnected.

colony-operations disconnect: No name confirmation required. Disconnecting disables automated review comments and issue label management; code generation via colony-coder continues unaffected.

Caution

Disconnecting colony-coder stops all pipeline activity for the affected GitHub org immediately. Issues currently in processing are not automatically resumed when you reconnect — they may need to be re-queued manually.

Refresh connection status

The Refresh connection status button verifies that stored app connections are still active by attempting to generate an installation token for each one.

• Connections that are confirmed gone (GitHub returns a definitive removal response) are removed from Colony Cloud.
• Connections where verification fails transiently (GitHub outage, network error) are preserved — Colony does not remove them on uncertainty.
• Connections that are successfully verified remain unchanged.

Refresh does not discover new installations. New connections are recorded only via the GitHub App install flow described above.

Note

Use Refresh when a connection shows as active in Colony Cloud but Colony is not processing issues — for example, after uninstalling and reinstalling the app on GitHub without going through the disconnect flow in Colony Cloud.

Repositories

The Repositories section lists every repository that colony-coder has been granted access to across all connected GitHub orgs. Use the toggle next to each repository to control whether Colony processes issues in it.

Toggle state	Behavior
Enabled	Colony monitors and processes new issues for this repository
Disabled	Colony ignores new issues; existing pipeline runs are not interrupted

Toggling a repository on or off takes effect immediately.

Adding repositories to the list

The list only shows repositories that the colony-coder GitHub App has been explicitly granted access to. If a repository you want to enable is not listed:

1. Go to your GitHub organization settings.
2. Navigate to Installed GitHub Apps → colony-coder → Configure.
3. Under Repository access, add the repository.
4. Return to Colony Cloud — the repository appears in the list immediately.

Disabling a repository

1. Locate the repository in the list.
2. Click its toggle to turn it off.
3. Confirm the dialog. Colony stops picking up new issues for this repository immediately.

Disabling a repository does not delete any history or configuration. Re-enable it at any time by toggling it back on.

Note

Disabling a repository here is distinct from uninstalling the GitHub App. To fully revoke Colony’s GitHub access, uninstall colony-coder from your GitHub organization settings.

Role permissions

Action	Required role
Install colony-coder or colony-operations	Owner or Admin
Connect another GitHub org	Owner or Admin
Disconnect an app	Owner or Admin
Refresh connection status	Owner or Admin
Enable or disable a repository	Owner or Admin
View the repository list	Any member

Note

Members and Viewers can open the Repos & access page and see which repositories are enabled or disabled, but all toggles and management actions are disabled. A note — “Contact an organization admin to enable or disable repositories” — appears in place of the controls.

API reference

Method	Path	Required role	Description
GET	/api/orgs/:orgId/installations	Owner, Admin	List all GitHub App installations for the org
POST	/api/orgs/:orgId/installations/refresh	Owner, Admin	Verify stored connections and remove confirmed-gone ones
POST	/api/orgs/:orgId/installations/:appType/connect	Owner, Admin	Initiate a GitHub App installation (returns install URL)
DELETE	/api/orgs/:orgId/installations/:appType	Owner, Admin	Disconnect a GitHub App installation
GET	/api/orgs/:orgId/repos	Any member	List repositories accessible to colony-coder
PUT	/api/orgs/:orgId/repos/:externalRepoId	Owner, Admin	Enable or disable a repository

:appType is coder or operations. On DELETE, pass ?externalOrgId=<id> to scope the disconnect to a specific GitHub org in a multi-tenant setup.