Troubleshooting

Can’t install the GitHub App

Symptoms: The GitHub App installation page errors, the app is greyed out, or the installation completes but Colony Cloud still shows the app as disconnected.

Common causes and fixes:

You do not have GitHub organization owner permissions. Installing a GitHub App on an organization requires org owner access. Confirm your role under your GitHub organization’s People settings. Ask an org owner to install the app, or have your account elevated to owner before proceeding.
The app is already installed on a different account. If colony-coder appears greyed out or unavailable, it may already be installed on a personal account rather than the organization account you are trying to manage. Go to GitHub → Settings → Applications → Installed GitHub Apps for the relevant account and check whether Colony is already listed. If it is installed in the wrong place, uninstall it there, then reinstall from Settings → GitHub Apps in Colony Cloud.
Colony Cloud shows Disconnected after installation. Return to Settings → GitHub Apps in Colony Cloud and click Refresh status. If the app still shows Disconnected, try uninstalling and reinstalling from Colony Cloud rather than directly from GitHub — the Colony Cloud flow sets up the organization mapping that GitHub’s native install page does not.

See Sign Up & Onboarding for the step-by-step GitHub App installation instructions.

A repo won’t enable

Symptoms: The repository does not appear in the Enable repository dialog, or it appears but enabling it fails or leaves the repository in an error state.

Common causes and fixes:

colony-coder is not installed on the account that owns the repository. This is the most common cause. The Enable repository dialog only lists repositories accessible to the colony-coder GitHub App. If your target repository is missing, open Settings → GitHub Apps and confirm that colony-coder is installed on the correct GitHub organization or personal account, and that the repository is included in the app’s repository access scope. If the app is installed with “Selected repositories” access, add the missing repository in the GitHub App settings, then return to Colony Cloud and try again.
The repository is archived on GitHub. Archived repositories are read-only on GitHub. Colony cannot open branches or create pull requests in an archived repository. Unarchive the repository on GitHub before enabling it in Colony Cloud.
The repository is private and outside the app’s permission scope. For private repositories, confirm that colony-coder’s installation has explicit read/write access to that repo (not just the organization level). Adjust the app’s repository scope in GitHub’s installation settings.
The enable operation fails with an error. If enabling succeeds on the UI but the repository shows an error status, check that your Colony Cloud organization’s GitHub account selection (set during org creation) matches the GitHub account that owns the repository. A mismatch between the org’s linked GitHub account and the repository’s owner prevents Pipeline Store registration.

An issue is stuck

Symptoms: An issue has been in the same pipeline state — analyzing, planning, in-development, or another active state — for more than 30 minutes without visible progress.

Common causes and fixes:

A worker went stale. The most likely cause is that the worker handling the issue stopped sending heartbeats — the container crashed, lost network, or was restarted. Open the Operator Home dashboard and check the Workers metric. If the worker count dropped unexpectedly, a worker is down. Restart or replace the affected container. Colony will reassign the issue to an available worker.
The issue exhausted its retries and went to the DLQ. If the issue has failed its task multiple times, the task is sent to the dead-letter queue (DLQ). Check the DLQ depth metric on Operator Home. A non-zero count means one or more tasks need manual resolution. Navigate to Settings → Dead Letters to inspect the failed task, view the error, and decide whether to retry or discard it.
The issue is waiting on a subtask. If the issue is in waiting-for-subtasks state, Colony is blocking progress until a related sub-issue completes. Check whether the subtask is itself stuck and address it first.
Pipeline Live shows an unexpected state. Open Pipeline Live and locate the issue. The state label and elapsed time tell you exactly where it is in the pipeline and how long it has been there. Use this to determine whether the issue is progressing slowly or genuinely blocked.

Worker isn’t picking up jobs

Symptoms: Workers are registered and visible in Settings → Workers, but new pipeline issues are not being assigned to them. Issues stay in analyzing or planning state without being picked up.

Common causes and fixes:

The worker’s Active status is missing or Stale. Open Settings → Workers and check the worker’s status. A Stale status means the container missed its heartbeat window. The container may have stopped or lost network connectivity. Check the container logs and restart it if needed. Once the container resumes heartbeats, the worker returns to Active and begins picking up jobs within one heartbeat interval.
COLONY_CLOUD_TOKEN is not set or is incorrect. The worker container must have the COLONY_CLOUD_TOKEN environment variable set to the token generated in Settings → Workers. An incorrect or missing token causes the /api/worker/register call to return 401, and the container exits. Check container logs for authentication errors and verify the token value.
COLONY_CLOUD_URL is not set correctly. The worker must have COLONY_CLOUD_URL=https://runcolony.com set in its environment. An incorrect URL means the worker cannot reach the Colony Cloud API. Container logs will show connection errors on startup.
The token was revoked. If a token was previously revoked in Settings → Workers, any container still using it will not be able to register. Generate a new token and redeploy the container with the new value.

See Workers (BYO) for full registration instructions and configuration reference.