cc-os/plugins/os-vault/eval/fixture/vault/howto/rotating-forgejo-runner-tokens.md

type	title	summary	tags	scope	last_updated	date	update_note
howto	Rotating Forgejo Runner Tokens	Steps to rotate a Forgejo Actions runner registration token without losing queued jobs.	type/howto tool/forgejo	global	2026-06-22	2026-06-22	experience-driven

Forgejo Actions runners register with a token scoped to an org or repo. Rotating it periodically (or after a suspected leak) is a manual process — there's no auto-rotation.

Steps

1. On the Forgejo web UI, go to the org (or repo) Settings → Actions → Runners.
2. Generate a new registration token; copy it immediately (it's shown once).
3. On the runner host, stop the running act_runner service before touching config: systemctl stop act_runner.
4. Edit .runner in the runner's data directory (or re-run act_runner register interactively) and replace the token value.
5. Restart the service: systemctl start act_runner.
6. Confirm the runner reappears as "Online" in the Runners settings page within ~30s.

Gotchas

• Rotating the token does not cancel jobs already queued against the old runner identity — they'll pick up once the runner reconnects with the new token, as long as you don't also delete the runner record.
• If you delete the old runner record instead of just rotating its token, any in-flight job assigned to it is orphaned and needs to be manually re-triggered.
• Multiple runners sharing one token (a pool) all need re-registering — there's no bulk rotation across a pool.