grm/docs/user/troubleshooting.md

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 registration token has not expired — generate a new one from Gitea if needed (Site Administration → Actions → Runners → Create Registration Token).
• 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
   • The registration token is valid and has not expired
   • 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