Skip to content

Troubleshooting

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

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 grayed 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 Account → Tenants → your tenant → Repositories (/account/tenants/:tenantId/repositories) in Colony Cloud.
  • Colony Cloud shows Not connected after installation. Return to Account → Tenants → your tenant → Repositories in Colony Cloud and click Refresh connection status. If the app still shows Not connected, 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 In & Onboarding for installation and Troubleshoot Webhooks and Provider Permissions for delivery and permission diagnosis.

Symptoms: The repository does not appear in the Repositories list, 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 Repositories list only shows repositories accessible to the colony-coder GitHub App. If your target repository is missing, open Account → Tenants → your tenant → Repositories 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. The error appears next to the repository’s name. Check that colony-coder is installed on the GitHub account that owns the repository, and that you’re on that account’s tenant under Account → Tenants.

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

Common causes and fixes:

  • A Worker stopped sending heartbeats. The most likely cause is that the Worker handling the issue stopped sending heartbeats — the container crashed, lost network, or was restarted. Open Operations → Fleet (/operations/fleet) and check each Worker’s status. If a Worker shows as offline with an old Last Heartbeat, it is down. Restart or replace the affected container. Colony will reassign the issue to an available Worker.
  • A transition exhausted its retries and produced a dead letter. Open Dead Letters (/operations/throughput?view=failed) first to see the unresolved records, and inspect the issue’s timeline in the Ledger for related failure context. See Recover a Dead-Lettered Issue for how to retry or resolve a record.
  • 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.
  • The Ledger shows an unexpected state. Open the Ledger (/work), find the issue and open its row to see the work-item sheet. The state, timeline 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.

Symptoms: The pipeline shows an issue moving forward, but the pull request, comment, label or merge you expected never showed up on your code host.

Common causes and fixes:

  • The write failed and is waiting for you. Colony queues a VCS write that fails with a temporary error and retries it. Open Write Queue (/operations/throughput?view=writes&status=failed), find the repository and issue, and read the Error column. Choose Retry once the cause is fixed (for example, restored app permissions), or Discard to drop the change. See Write Queue.
  • The write is still pending. Check /operations/throughput?view=writes&status=pending. A write waiting for its next retry will land by itself.
  • The issue itself is stuck. If Write Queue is empty, the pipeline may have failed earlier. Check Dead Letters and see Recover a Dead-Lettered Issue.

Symptoms: Workers are registered and visible in Operations → Fleet, 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 shows as offline. Open Operations → Fleet and check the Worker’s Status and Last Heartbeat. An offline Worker with an old Last Heartbeat 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 online 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 Operations → Fleet. 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 set to the wrong host. COLONY_CLOUD_URL is optional and defaults to https://app.runcolony.com. You only need to set it if you are pointing Workers at a custom endpoint — do not set it to https://runcolony.com. An incorrect URL means the Worker cannot reach the Colony Cloud API; container logs will show connection errors on startup.
  • The token was revoked. (Active and Revoked are labels on registration tokens, not Worker statuses.) If a token was previously revoked in Operations → Fleet, 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 for registration and controls, and Operate and Scale Workers for capacity and recovery decisions.