---
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.