feat: introduce experimental command connect with token option #1259

Merged

mfenniak merged 1 commit from aahlenst/runner:connect-command into main

2026-01-08 22:52:16 +00:00

aahlenst commented

2026-01-07 14:42:41 +00:00

Member

Introduce the experimental command forgejo-runner connect token for connecting Forgejo Runner to a Forgejo instance using the runner token. The runner token can be obtained by registering a new runner using Forgejo's HTTP API. It is required to enable runner management using Forgejo's HTTP API instead of using forgejo-runner register. That is useful when runner instances are managed by automation or separate applications.

Example usage:

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: token 3fc3ef39805b0f811a5d7789cb7b448348d6bfbb" \
    --data '{"name":"api-runner","description":"Lorem ipsum"}' \
    http://localhost:3000/api/v1/user/actions/runners

{"id":30,"uuid":"a5e33697-9f58-437d-83c3-551b6c6a6334","token":"cac45fa6726fe4e28f42598773671af28a3be121"}

The uuid and token can then be passed to forgejo-runner connect token:

$ forgejo-runner connect token \
    --instance http://localhost:3000 \
    --name api-runner \
    --uuid a5e33697-9f58-437d-83c3-551b6c6a6334 \
    --token cac45fa6726fe4e28f42598773671af28a3be121 \
    --label debian:docker://node:24-trixie \
    --label docker:docker://node:24-trixie

See forgejo/forgejo-actions-feature-requests#78 for details and design considerations.

Predefined labels in a runner configuration file are currently ignored.

features
- PR: feat: introduce experimental command connect with token option

Introduce the experimental command `forgejo-runner connect token` for connecting Forgejo Runner to a Forgejo instance using the runner token. The runner token can be obtained by registering a new runner using Forgejo's HTTP API. It is required to enable runner management using Forgejo's HTTP API instead of using `forgejo-runner register`. That is useful when runner instances are managed by automation or separate applications. Example usage: ``` $ curl -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: token 3fc3ef39805b0f811a5d7789cb7b448348d6bfbb" \ --data '{"name":"api-runner","description":"Lorem ipsum"}' \ http://localhost:3000/api/v1/user/actions/runners ``` ```json {"id":30,"uuid":"a5e33697-9f58-437d-83c3-551b6c6a6334","token":"cac45fa6726fe4e28f42598773671af28a3be121"} ``` The `uuid` and `token` can then be passed to `forgejo-runner connect token`: ``` $ forgejo-runner connect token \ --instance http://localhost:3000 \ --name api-runner \ --uuid a5e33697-9f58-437d-83c3-551b6c6a6334 \ --token cac45fa6726fe4e28f42598773671af28a3be121 \ --label debian:docker://node:24-trixie \ --label docker:docker://node:24-trixie ``` See https://code.forgejo.org/forgejo/forgejo-actions-feature-requests/issues/78 for details and design considerations. Predefined labels in a runner configuration file are currently ignored.   - features - [PR](https://code.forgejo.org/forgejo/runner/pulls/1259): feat: introduce experimental command connect with token option

aahlenst added 1 commit

2026-01-07 14:42:42 +00:00

feat: introduce experimental command connect with token option

issue-labels / release-notes (pull_request_target) Successful in 6s

Details

checks / validate pre-commit-hooks file (pull_request) Successful in 1m7s

Details

checks / validate mocks (pull_request) Successful in 1m16s

Details

checks / build and test (pull_request) Successful in 5m11s

Details

checks / runner exec tests (pull_request) Successful in 42s

Details

checks / runner integration tests (pull_request) Successful in 8m18s

Details

checks / integration tests (docker-latest) (pull_request) Successful in 14m58s

Details

checks / integration tests (docker-stable) (pull_request) Successful in 17m5s

Details

cascade / debug (pull_request_target) Has been skipped

Details

cascade / end-to-end (pull_request_target) Successful in 3s

Details

cascade / forgejo (pull_request_target) Successful in 1m14s

Details

0c7a024afe

mfenniak approved these changes

2026-01-08 22:50:24 +00:00

mfenniak left a comment

Owner

Reviewed, looks good. Pulled down and performed a manual test -- I was a little surprised that the command didn't validate token remotely, but I see that was noted as an open question in your design that was never addressed. I don't consider that a blocker at all; if the behaviour turns out to be desired for any practical reason other than my surprise, it can be added later.

Thanks!