Migration
If you are running Colony on your own infrastructure and want to move to Colony Cloud, this guide walks you through the cutover. The process is additive: you set up Colony Cloud in parallel with your existing install, validate it, then decommission the old instance.
Before you migrate
Section titled “Before you migrate”Take stock of what your self-hosted install is managing:
- Repositories — list all repos in
colony.config.yamlunderrepos(or in your org’s tenant config). You will re-enable each one in Colony Cloud. - Secrets — identify any environment variables or secrets passed to the Colony container (API keys, tokens, credentials). You will re-enter these in Colony Cloud’s encrypted secret store.
- Worker tokens — if you run additional Worker containers, note how many and where they are deployed. You will generate new Cloud tokens and retire the old containers.
- Pipeline config — note any custom values under
agents.workers(heartbeat interval, retry limits, task duration) that differ from Colony’s defaults. You will re-apply these via Settings in Colony Cloud.
Create your Colony Cloud organization
Section titled “Create your Colony Cloud organization”Colony Cloud is invitation-only. If you do not yet have an account, ask your Colony contact for an invitation, then follow Sign In & Onboarding to sign in. Return here once you can open your organization.
Install the GitHub Apps
Section titled “Install the GitHub Apps”Colony Cloud uses two GitHub Apps — colony-coder (required) and colony-operations (optional). Follow the GitHub Apps installation steps in Sign In & Onboarding to install them on the same GitHub account or organization that owns your repositories.
Enable your repositories
Section titled “Enable your repositories”- In Colony Cloud, open Account → Tenants → your tenant → Repositories (
/account/tenants/:tenantId/repositories). - Turn on the toggle for each repository you were managing in your self-hosted install, or select several and click the Enable button above the list.
- Confirm that each repository’s toggle stays on.
See Connect a Repository for repository settings and Operate and Scale Workers for the current tenant-pool and repository-scoped Worker models.
Migrate your secrets
Section titled “Migrate your secrets”Re-enter each secret from your self-hosted environment into Colony Cloud’s encrypted secret store.
- Open Operations → Settings (Secrets) in Colony Cloud.
- For each credential from your old install that has a card on the page (for example, the Anthropic or OpenAI API key), paste the value into its input.
- Click Save on each card (Save the key on the Anthropic card, which checks the key with Anthropic first).
These cards accept a fixed set of keys. For a custom environment variable that a repository’s build or agents need, use Repository secrets, which multi-repository pool Workers fetch.
Secrets are encrypted at rest using AES-GCM. The plaintext value is never stored after saving. See Secrets for full management instructions.
Migrate your Workers
Section titled “Migrate your Workers”If you run BYO Worker containers alongside the managed Colony process, generate new Cloud Worker tokens and redeploy the containers.
-
Open Operations → Fleet (
/operations/fleet). -
Under Registration Tokens, type a descriptive name (for example,
prod-worker-us-east) and click Generate. Copy the token — it is shown only once. -
Update your container deploy to use the new credentials. First create
colony.envin an editor, with the single lineCOLONY_CLOUD_TOKEN=<your-new-token>, and runchmod 600 colony.env. Typing the token into a shell command would leave it in your shell history. Then run:Terminal window # Read the token from colony.env so it stays out of shell historysed -n 's/^COLONY_CLOUD_TOKEN=//p' colony.env | docker login registry.runcolony.com -u colony --password-stdin# Sprint-master — coordinates work across all repos (one per org)docker run -d \--name colony-sprint-master-<connected org id> \--restart unless-stopped \--env-file colony.env \-e COLONY_CLOUD_URL=https://app.runcolony.com \-e COLONY_ROLE=sprint-master \-e COLONY_EXTERNAL_ORG_ID=<connected org id> \-e COLONY_WORKER_NAME=colony-sprint-master-<connected org id> \registry.runcolony.com/colony-managed:<release># Worker, per repository — one container per repositorydocker run -d \--name colony-worker-owner-repo-1 \--restart unless-stopped \--env-file colony.env \-e COLONY_CLOUD_URL=https://app.runcolony.com \-e COLONY_REPO=owner/repo \-e COLONY_WORKER_NAME=colony-worker-owner-repo-1 \registry.runcolony.com/colony-managed:<release># Worker, multi-repository pool — one container serves every repositorydocker run -d \--name colony-worker-<connected org id>-1 \--restart unless-stopped \--env-file colony.env \-e COLONY_CLOUD_URL=https://app.runcolony.com \-e COLONY_EXTERNAL_ORG_ID=<connected org id> \-e COLONY_WORKER_NAME=colony-worker-<connected org id>-1 \-v colony-objects-<connected org id>:/colony/objects \registry.runcolony.com/colony-managed:<release>COLONY_CLOUD_URLdefaults tohttps://app.runcolony.com, so you can omit it unless you were given a different address. The env valuesprint-masteris the process these docs call the Mayor: it handles cross-repo coordination and needs your org ID to start. Each per-repository Worker handles pipeline tasks for one repository; replaceowner/repowith your repository path (for example,acme/my-repo). A multi-repository pool Worker serves all of the org’s repositories from one container. The explicit name keeps a Worker’s identity when you recreate its container; see Replacing or upgrading workers. -
Confirm the Workers show as
onlineorbusywith a fresh heartbeat on Operations → Fleet within a few seconds of their first heartbeat. -
Once the new Workers are healthy, stop the old Worker containers.
See Workers (BYO) for full details on Worker registration and operation.
Validate Colony Cloud
Section titled “Validate Colony Cloud”Before decommissioning your self-hosted install, confirm Colony Cloud is working end-to-end:
- Open a test issue in one of your enabled repositories and confirm Colony picks it up and moves it through the pipeline.
- Check the Fleet tile on Operations → Health for the Worker count (“N of M workers running”), and the Ledger (
/work) to follow issue flow. - Verify secrets are available to Workers by watching a task that relies on one of your migrated secrets.
Decommission the self-hosted install
Section titled “Decommission the self-hosted install”Once Colony Cloud is handling traffic reliably:
- Stop the self-hosted Colony container (or service).
- If you configured GitHub webhooks pointing at the old install, remove or update them. Colony Cloud manages its own webhook infrastructure — no manual webhook configuration is required.
- Archive or remove your
colony.config.yamland any associated secrets from the host machine.