Connect a Repository

Connecting a repository tells Colony Cloud to manage that repository’s issues through the autonomous pipeline. You can connect multiple repositories under the same organization.

Enable a repository

1. In Colony Cloud, open Repositories from the left navigation.
2. Click Enable repository. A list of repositories accessible to the colony-coder GitHub App appears. If your target repository is not listed, check that colony-coder is installed on the correct GitHub account or organization under Settings → GitHub Apps.
3. Select the repository you want to connect and click Enable.

Enabling a repository writes two records simultaneously:

• A row in the Colony Cloud database (org_repos) linking the repository to your organization.
• Records in Colony’s Pipeline Store (tenants, repos, repo_configs) that register the repository with the autonomous pipeline and apply your organization’s default configuration.

After enabling, the repository appears in the Repositories list with a status of Active. Colony begins monitoring new issues immediately.

Note

Colony only processes issues in repositories that are explicitly enabled. Issues in disabled repositories are ignored even if colony-coder is installed on the GitHub account.

Configure repository settings

Each repository has its own pipeline configuration. Open the repository’s settings to customize how Colony handles it.

1. In Repositories, click the repository name to open its detail page.
2. Select the Settings tab.

Conventions

The most important configuration for a repository is its .colony/conventions.md file — a Markdown document that describes the codebase’s tech stack, coding conventions, forbidden patterns, and review priorities. Colony’s agents read this file before analyzing, developing, or reviewing any issue in the repository.

Place .colony/conventions.md in the repository root and commit it to the default branch. Colony reads the file on every pipeline run — changes take effect immediately without reconfiguring the repository in Colony Cloud.

See the Operator role for guidance on writing an effective conventions.md.

Pipeline tracks

Self-improvement (SI) tracks let Colony propose work proactively — for example, flagging tech debt, generating test coverage, or applying dependency updates — without waiting for a human to file an issue. Configure tracks on the Settings → Tracks tab:

• Enable tracks — toggle to allow Colony to propose issues based on this track type.
• Cooldown — minimum time between track runs (in minutes). Prevents the track from filing too many issues in a short window.
• Labels — optional GitHub labels to apply to issues Colony files from this track.

Tip

Start with a single track type and a long cooldown (1440 minutes = 24 hours). Review what Colony proposes for a week before enabling additional tracks or shortening the cooldown.

Worker sizing

The per-repository worker allocation controls how many issues in this repository can run in parallel. The default inherits from the organization setting; override it here if one repository needs a different share of capacity.

Change the concurrent workers value and click Save. The change takes effect within 60 seconds — active workers are not interrupted.

Disable a repository

Disabling a repository tells Colony to stop processing new issues. It does not delete any history or configuration.

1. In Repositories, click the repository name.
2. On the Settings tab, scroll to Danger zone and click Disable repository.
3. Confirm the dialog.

When you disable a repository:

• Colony stops picking up new issues immediately.
• Issues currently being worked (in states such as in-development or in-review) are allowed to finish their current task. They are not aborted mid-run.
• The repository row in org_repos is marked inactive. No Pipeline Store data is deleted.
• The repository disappears from the Active list and moves to Disabled. Re-enable it at any time by clicking Enable from the Disabled tab.

Caution

Disabling a repository does not uninstall the colony-coder GitHub App. To revoke Colony’s GitHub access entirely, uninstall the app from your GitHub organization settings.