emil
5b05db4e6d
Add /docs/ directory with user and technical documentation extracted from README, AGENTS.md, and source code. Add scripts/sync_wiki.py to sync docs to Gitea wiki via API. Add scripts/doc_coverage.py to check CLI commands, modules, and CI scripts are documented. Add sync-wiki.yml workflow for auto-sync on merge and release. Slim down README.md to lean entry point. 28 new unit tests, 100% coverage maintained. Closes GRM-36
51 lines
3.3 KiB
Markdown
51 lines
3.3 KiB
Markdown
# Troubleshooting
|
|
|
|
## "Event loop is closed" warning
|
|
|
|
This is a harmless cleanup traceback from Molecule's Docker driver when the test process is interrupted. It does not indicate a test failure.
|
|
|
|
## Runner appears offline after installation
|
|
|
|
- Check that the `GITEA_URL` and `GITEA_REGISTRATION_TOKEN` environment variables are correct.
|
|
- Verify the runner service is running: `sudo -u grm-<name> systemctl --user status gitea-runner`.
|
|
- Check logs for registration errors.
|
|
|
|
## Integration test fails
|
|
|
|
The test checks two things:
|
|
|
|
1. **`.runner` file missing or invalid** — Registration failed. Check:
|
|
- `GITEA_URL` and `GITEA_REGISTRATION_TOKEN` are correct
|
|
- Runner logs for registration errors
|
|
- The `.runner` file should exist at `/var/lib/gitea-runner/<name>/.runner`
|
|
|
|
2. **Service not running** — Daemon failed to start. Check:
|
|
- `sudo -u grm-<name> systemctl --user status gitea-runner`
|
|
- Logs for connection errors
|
|
|
|
## Rootless Docker: service fails to start
|
|
|
|
- Check the service status: `sudo -u grm-<name> systemctl --user status gitea-runner`.
|
|
- Verify the rootless Docker daemon is running: `sudo -u grm-<name> systemctl --user status docker`.
|
|
- Verify the Docker socket exists: `ls /run/user/$(id -u grm-<name>)/docker.sock`.
|
|
- Check logs: `sudo -u grm-<name> journalctl --user -u gitea-runner -f`.
|
|
- Ensure lingering is enabled for the runner user: `loginctl show-user grm-<name> | grep Linger`.
|
|
|
|
## Common Issues Reference Table
|
|
|
|
| Symptom | Likely Cause | Solution |
|
|
|---------|-------------|----------|
|
|
| Pre-commit rejects commit message | Missing conventional format or GRM-N prefix present | Use `feat: description` format without `GRM-N:` |
|
|
| `make molecule` fails with `runner_name is undefined` | Verify playbook missing variable | Fixed in Phase 1.1; ensure you're on latest master |
|
|
| CI molecule job fails | Docker not available on runner host | Ensure Gitea runner host has Docker installed and running |
|
|
| Auto-merge doesn't trigger | Label not exactly `ready-to-merge` or CI checks not all green | Verify label spelling; check CI status |
|
|
| Vikunja task not updated after merge | VIKUNJA_TOKEN expired or task ID missing from commit | Regenerate token; verify merge commit has `GRM-N:` prefix |
|
|
| Post-merge can't find Vikunja task | Task not in project 6 or identifier mismatch | Verify task exists in Vikunja project 6 with correct identifier |
|
|
| `make pytest-cov` fails | Coverage below 100% | Add tests for new code paths |
|
|
| `scripts/configure_repo.py` fails | REPO_TOKEN missing or invalid | Set token with repo admin scope and re-run |
|
|
| `configure_repo.py` sets wrong status checks | Stale `BRANCH_PROTECTION_CONFIG` | Updated to include `(pull_request)` suffix; re-run `configure_repo.py` |
|
|
| Token visible in `ps aux` during install | Old version passed tokens via command line | Fixed: tokens now passed via temp file with `0600` permissions |
|
|
| `remove-runner.yml` leaves lingering enabled | Old version didn't disable lingering | Fixed: now runs `loginctl disable-linger` and removes subuid/subgid |
|
|
| apt cache update always reports `changed` | `cache_valid_time: 0` forced update every run | Fixed: changed to `cache_valid_time: 3600` |
|
|
| Prune/service templates created even when `docker_rootless_setup: false` | Template tasks not guarded | Fixed: template creation now guarded by `docker_rootless_setup` |
|