37 lines
1.5 KiB
Markdown
37 lines
1.5 KiB
Markdown
|
---
|
||
|
|
type: howto
|
||
|
|
title: Rotating Forgejo Runner Tokens
|
||
|
|
summary: Steps to rotate a Forgejo Actions runner registration token without losing queued jobs.
|
||
|
|
tags:
|
||
|
|
- type/howto
|
||
|
|
- tool/forgejo
|
||
|
|
scope: global
|
||
|
|
last_updated: 2026-06-22
|
||
|
|
date: 2026-06-22
|
||
|
|
update_note: 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.
|