# 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:

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

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

   ```bash
   ./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)

```bash
# 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 .
```