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

Take stock of what your self-hosted install is managing:

Repositories — list all repos in colony.config.yaml under repos (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

If you do not yet have a Colony Cloud account, follow the Sign Up & Onboarding guide to create an account and an organization. Return here once your organization is set up.

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 Up & Onboarding to install them on the same GitHub account or organization that owns your repositories.

Enable your repositories

In Colony Cloud, open Repositories from the left navigation.
Click Enable repository and select each repository you were managing in your self-hosted install.
Confirm that each repository shows Active status after enabling.

See Connect a Repository for full details on repository settings, including pipeline tracks and per-repo worker allocation.

Migrate your secrets

Re-enter each secret from your self-hosted environment into Colony Cloud’s encrypted secret store.

Open Settings → Secrets in Colony Cloud.
For each secret from your old install, click New secret, enter the name (uppercase letters, digits, and underscores — e.g., OPENAI_API_KEY), and enter the value.
Click Save secret for each one.

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

If you run BYO worker containers alongside the managed Colony process, generate new Cloud worker tokens and redeploy the containers.

Open Settings → Workers in Colony Cloud.
Click Generate token for each logical worker group. Give each token a descriptive label (e.g., prod-worker-us-east). Copy each token — it is shown only once.

Update your container deploy to use the new credentials:

docker run -d \
  -e COLONY_CLOUD_TOKEN=<your-new-token> \
  -e COLONY_CLOUD_URL=https://runcolony.com \
  registry.runcolony.com/colony-managed:latest

Confirm the workers appear as Active in Settings → Workers within a few seconds after 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

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 Operator Home dashboard to confirm worker count and issue counts are as expected.
Verify secrets are available to workers by watching a task that relies on one of your migrated secrets.

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.yaml and any associated secrets from the host machine.