q-blog/docs/CI_RUNNER_TROUBLESHOOTING.md

CI Runner Troubleshooting (Quick)

If a workflow shows Waiting indefinitely, it’s almost always one of:

1. No runner matches labels – This workflow requires only the self-hosted label. Ensure your runner config includes it:

   runner:
     capacity: 1
     labels: ['self-hosted', 'linux', 'x64']
   

2. Runner offline – start the runner process and watch logs:

   ./run.sh   # or the systemd service you configured
   

   You should see “listening for jobs”.

3. Another job occupying capacity – your runner has capacity: 1. Cancel the stuck job in Actions UI.

4. Repo visibility / permissions – ensure Actions are enabled for this repo and the runner is allowed to pick jobs from it.

This repo’s workflow doesn’t use marketplace actions, Docker, or services—so a plain runner works.

Verify via API (optional)

# runs list
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_BASE_URL/api/v1/repos/$OWNER/$REPO/actions/runs?limit=5" | jq .

# a specific run
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_BASE_URL/api/v1/repos/$OWNER/$REPO/actions/runs/{run_id}" | jq .