Skip to content

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.

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.

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.

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.

  1. In Colony Cloud, open Account → Tenants → your tenant → Repositories (/account/tenants/:tenantId/repositories).
  2. 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.
  3. 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.

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

  1. Open Operations → Settings (Secrets) in Colony Cloud.
  2. 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.
  3. 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.

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

  1. Open Operations → Fleet (/operations/fleet).

  2. Under Registration Tokens, type a descriptive name (for example, prod-worker-us-east) and click Generate. Copy the token — it is shown only once.

  3. Update your container deploy to use the new credentials. First create colony.env in an editor, with the single line COLONY_CLOUD_TOKEN=<your-new-token>, and run chmod 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 history
    sed -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 repository
    docker 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 repository
    docker 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_URL defaults to https://app.runcolony.com, so you can omit it unless you were given a different address. The env value sprint-master is 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; replace owner/repo with 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.

  4. Confirm the Workers show as online or busy with a fresh heartbeat on Operations → Fleet within a few seconds of their first heartbeat.

  5. Once the new Workers are healthy, stop the old Worker containers.

See Workers (BYO) for full details on Worker registration and operation.

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.

Once Colony Cloud is handling traffic reliably:

  1. Stop the self-hosted Colony container (or service).
  2. 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.
  3. Archive or remove your colony.config.yaml and any associated secrets from the host machine.