Go from Zero to First Autonomous Merge

This guide takes a GitHub repository from initial setup to its first Colony-authored pull request. Start with a small, verifiable issue so that the first run tests the installation and workflow rather than the limits of autonomous development.

Before you start

You need administrator access to the repository and permission to install a GitHub App. Read Core Concepts and The Workflow if the pipeline vocabulary is new to you.

Create your Colony Cloud account and organization. See Sign Up & Onboarding for the current sign-in options.
Install colony-coder on the target repository. Install colony-operations as well for issue operations and GitHub review publication used by the full workflow.
Enable the repository in Colony Cloud. Follow Connect a Repository if the app installation or repository is not listed.
Open the repository’s Settings page and check its intake mode. All issues ingests every new issue; Tagged only ingests only issues carrying the Colony intake label.
Confirm at least one Worker is online before creating the test issue.

Complete Installation and GitHub App Setup.
Add the repository to the Colony installation’s colony.config.yaml, then initialize it as described in First Issue.
Run colony status --check to validate configuration, provider access, and projection labels.
Run colony status --db and confirm the Mayor and at least one Worker are healthy.

Create and enqueue the first issue

Choose a bounded change with an observable result. Explain the problem, the desired behavior, and how a reviewer can tell the work is complete. File references and suggested tests help when you know them, but they are not mandatory fields. See Writing for Colony for examples.

How the issue enters Colony depends on intake mode:

With All issues, create a new issue after the repository is enabled.
With Tagged only, add the colony:enqueue label. You can also post /colony:enqueue on an eligible existing issue.

If Colony asks for clarification, answer in a new issue comment. Editing the issue body alone is not the clarification event the pipeline is waiting for.

Follow the run

In Colony Cloud, use Pipeline (/dashboard/pipeline) or Pipeline Live. On GitHub, colony:* labels are a projection of the database state; they are useful signals but not the source of truth.

A simple issue normally passes through analysis, development, automated review, and then one of two endings:

If automatic merge is disabled, the issue reaches human-review-ready. Review and merge the pull request in GitHub.
If automatic merge is enabled and all required conditions pass, Colony moves through merge-pending and attempts the merge.

Planning, decomposition, clarification, feedback, CI repair, and recovery states can add steps. The complete behavior is documented in Pipeline States.

Review the result

Check the diff, test results, and acceptance outcome. If the implementation is sound, approve and merge it when human review is required. If it needs a targeted revision, put the guidance in an issue comment containing /colony:feedback. Use /colony:reimplement only when the current approach and pull request should be discarded; valid actions depend on the issue’s pinned workflow.