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
3.3 KiB
3.3 KiB
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_URLandGITEA_REGISTRATION_TOKENenvironment 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:
-
.runnerfile missing or invalid — Registration failed. Check:GITEA_URLandGITEA_REGISTRATION_TOKENare correct- Runner logs for registration errors
- The
.runnerfile should exist at/var/lib/gitea-runner/<name>/.runner
-
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 |