Forgejo API
POST/admin/actions/runners

Register a global Action runner

Creates a new global Action runner registration. Supply name and optionally provide description or mark the runner as ephemeral. A 201 response returns the newly registered runner's identifier, registration token, and UUID.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

3 body fields

Options for registering a new global Action runner.

descriptionstringoptional
Description of the runner to register.
ephemeralbooleanoptional
Register as ephemeral runner https://forgejo.org/docs/latest/admin/actions/security/#ephemeral-runner
namestringrequired
Name of the runner to register. The name of the runner does not have to be unique.

4 status codes
201Returns the registered runner's numeric `id`, registration `token`, and `uuid`.
idintegeroptional
tokenstringoptional
uuidstringoptional
400Returned when the registration options are invalid, including when the required `name` is missing.
messagestringoptional
urlstringoptional
401Returned when the request is not authorized to register a global runner.
messagestringoptional
urlstringoptional
404Returned when the requested registration resource cannot be found.
errorsarray<string>optional
messagestringoptional
urlstringoptional

Error handling

name is required and must be supplied to register the runner. A 400 is returned when the registration options fail validation, a 401 when the request is unauthorized, and a 404 when the requested registration resource cannot be found.