Troubleshooting

Organised by what you can see, not by what went wrong internally. Find your symptom, and the cause follows.

My pull request is not entering the queue

Check the repository row shows Gondolier: enabled. The selector next to it turns the queue on and off per repository.

Check the PR is actually ready. Gondolier stages pull requests that are open, mergeable, and not draft. A PR with conflicts against the base branch is not mergeable and is skipped until you rebase it.

Check the branch pattern. The default is gondolier/*; a repository configured with a narrower pattern only queues PRs targeting matching branches.

Wait one tick. Reconciliation runs every five minutes. In poll wake mode that is the whole story — nothing is wrong, it is not your turn yet.

Check for Paused — payment required. If a payment is outstanding, only the oldest repositories up to the Free allowance keep running. See Billing.

The repository shows Not protected

That is the resting state, not an error. Gondolier does not change your branch protection at enrollment, because doing so changes how every pull request in that repository merges.

Click Protect base branch when you are ready. Until then the queue works, but nothing stops someone merging around it.

The CI gate says Waiting for CI and never finishes

Your CI is not running on the probe branch. Gondolier pushes a commit to a temporary gondolier/<base>/verify-… ref and watches for a workflow run.

Check your workflow triggers on gondolier/** pushes. This is the single most common cause:

on:
  push:
    branches: ['gondolier/**']

Check Actions are enabled for the repository on your forge.

Check the bot can push. The connection’s token needs write access to create the probe ref.

Verification is optional. If your existing CI already covers gondolier/**, you can skip the probe entirely — it exists to tell you whether it does, not to gate anything.

The repository shows Needs admin

The connection’s token lacks the permission for that provisioning step — registering a webhook or configuring branch protection both need repository admin.

Grant the bot account repo-admin scope on your forge, then click Provision to retry. The dashboard shows the manual equivalent if you would rather do it by hand.

The repository shows Needs bot username

The connection was saved without a bot account name. Gondolier needs to know which account it is acting as before it can configure protection. Edit the connection and set the bot’s username.

The repository shows Forge unreachable

Gondolier could not reach your forge over HTTPS.

• Confirm the instance URL is correct and reachable from the public internet.
• Confirm it is https:// — plain HTTP is rejected.
• Confirm the forge is not behind an allowlist that excludes Cloudflare.

Gondolier runs on Cloudflare Workers, so a forge only reachable from inside a private network cannot be managed by the hosted service.

Webhook mode is not firing

Check the webhook exists on the forge, pointing at https://api.gondolier.dev/api/v1/webhooks/forgejo, with push and pull_request events and active ticked.

Check the recent deliveries on your forge’s webhook page. A 401 means the signature did not verify — usually because the webhook secret was regenerated outside Gondolier. Click Provision to re-register it.

Nothing is lost either way. Webhook mode makes the queue prompt; the five-minute cron still reconciles every repository. A broken webhook makes merges slower, not absent.

A pull request was bounced

The queue identified it as the cause of a batch failure. That is the bisect working, not a bug.

Look at the failing run on the staging branch — the dashboard links it. Fix the problem and push; the PR re-enters the queue on the next tick. Nothing was closed or force-pushed.

If a PR is bounced repeatedly and the failure looks unrelated to it, the usual cause is a flaky test: the bisect attributes an intermittent failure to whatever PR was isolated when it fired.

Adding a repository fails

The dashboard shows the specific reason. The common ones:

Message	What it means
Already managed on this forge instance	Another repository record already covers it
free/pro tier allows N repos	You are at the plan ceiling — see Billing
Connection not found	The connection was removed; add it again
Could not check your plan limits	A transient failure on our side. Retry

The queue activity view is empty

No repositories enrolled shows an explicit empty state with an Add a repo action.

Repositories enrolled but no activity means nothing has been staged yet — expected until a pull request becomes ready.

“Unable to load activity” means the API call failed. Reload; if it persists, check status.gondolier.dev.

Something else

The status page reports whether the API itself is reachable. Note that it measures the API only — it does not currently monitor queue progress, and says so rather than showing a green light it cannot justify.