Skip to content

runners

Accessed as client.admin.actions.runners; the async client mirrors it.

AdminActionsRunners

The admin.actions.runners namespace.

delete 

delete(runner_id: str) -> None

Delete a particular runner, no matter whether it is a global runner or scoped to an organization, user, or repository.

Parameters:

Name Type Description Default
runner_id str

ID of the runner

 required

Returns:

Type Description
None

No content.

Raises:

Type Description
BadRequestError
  1. APIError is error format response.
NotFoundError
  1. APINotFound is a not found error response.

Operation ID: deleteAdminRunner

get 

get(runner_id: str) -> ActionRunner

Get a particular runner, no matter whether it is a global runner or scoped to an organization, user, or repository.

Parameters:

Name Type Description Default
runner_id str

ID of the runner

 required

Returns:

Type Description
ActionRunner

ActionRunner represents a runner.

Raises:

Type Description
BadRequestError
  1. APIError is error format response.
NotFoundError
  1. APINotFound is a not found error response.

Operation ID: getAdminRunner

jobs 

jobs(*, labels: str | None = None) -> list[ActionRunJob]

Get action run jobs.

Parameters:

Name Type Description Default
labels str | None

a comma separated list of labels to search for

 None

Returns:

Type Description
list[ActionRunJob]

RunJobList is a list of action run jobs.

Raises:

Type Description
ForbiddenError
  1. APIForbiddenError is a forbidden error response.

Operation ID: adminGetActionRunJobs

list 

list(*, visible: bool | None = None, page: int | None = None, limit: int | None = None) -> Paginated[ActionRunner]

Get all runners, no matter whether they are global runners or scoped to an organization, user, or repository.

Parameters:

Name Type Description Default
visible bool | None

whether to include all visible runners (true) or only those that are directly owned by the instance (false)

 None
page int | None

1-based page to start iteration at.

 None
limit int | None

Page size; the instance caps it server-side.

 None

Returns:

Type Description
Paginated[ActionRunner]

ActionRunnerList is a list of Forgejo Action runners.

Raises:

Type Description
BadRequestError
  1. APIError is error format response.
NotFoundError
  1. APINotFound is a not found error response.

Operation ID: getAdminRunners

register 

register(*, description: str | None = None, ephemeral: bool | None = None, name: str) -> RegisterRunnerResponse

Register a new global runner.

Parameters:

Name Type Description Default
description str | None

Description of the runner to register.

 None
ephemeral bool | None

Register as ephemeral runner https://forgejo.org/docs/latest/admin/actions/security/#ephemeral-runner

 None
name str

Name of the runner to register. The name of the runner does not have to be unique.

 required

Returns:

Type Description
RegisterRunnerResponse

RegisterRunnerResponse contains the details of the just registered runner.

Raises:

Type Description
BadRequestError
  1. APIError is error format response.
UnauthorizedError
  1. APIUnauthorizedError is a unauthorized error response.
NotFoundError
  1. APINotFound is a not found error response.

Operation ID: registerAdminRunner

registration_token 

registration_token() -> RegistrationToken

Get a runner registration token for registering global runners.

This operation has been deprecated in Forgejo 15. Use the web UI or /admin/actions/runners instead.

Returns:

Type Description
RegistrationToken

RegistrationToken is a string used to register a runner with a server.
Deprecated

Deprecated in the vendored Spec; generated for compatibility.

Operation ID: adminGetRunnerRegistrationToken

AsyncAdminActionsRunners

The admin.actions.runners namespace.

delete 

delete(runner_id: str) -> None

Delete a particular runner, no matter whether it is a global runner or scoped to an organization, user, or repository.

Parameters:

Name Type Description Default
runner_id str

ID of the runner

 required

Returns:

Type Description
None

No content.

Raises:

Type Description
BadRequestError
  1. APIError is error format response.
NotFoundError
  1. APINotFound is a not found error response.

Operation ID: deleteAdminRunner

get 

get(runner_id: str) -> ActionRunner

Get a particular runner, no matter whether it is a global runner or scoped to an organization, user, or repository.

Parameters:

Name Type Description Default
runner_id str

ID of the runner

 required

Returns:

Type Description
ActionRunner

ActionRunner represents a runner.

Raises:

Type Description
BadRequestError
  1. APIError is error format response.
NotFoundError
  1. APINotFound is a not found error response.

Operation ID: getAdminRunner

jobs 

jobs(*, labels: str | None = None) -> list[ActionRunJob]

Get action run jobs.

Parameters:

Name Type Description Default
labels str | None

a comma separated list of labels to search for

 None

Returns:

Type Description
list[ActionRunJob]

RunJobList is a list of action run jobs.

Raises:

Type Description
ForbiddenError
  1. APIForbiddenError is a forbidden error response.

Operation ID: adminGetActionRunJobs

list 

list(*, visible: bool | None = None, page: int | None = None, limit: int | None = None) -> AsyncPaginated[ActionRunner]

Get all runners, no matter whether they are global runners or scoped to an organization, user, or repository.

Parameters:

Name Type Description Default
visible bool | None

whether to include all visible runners (true) or only those that are directly owned by the instance (false)

 None
page int | None

1-based page to start iteration at.

 None
limit int | None

Page size; the instance caps it server-side.

 None

Returns:

Type Description
AsyncPaginated[ActionRunner]

ActionRunnerList is a list of Forgejo Action runners.

Raises:

Type Description
BadRequestError
  1. APIError is error format response.
NotFoundError
  1. APINotFound is a not found error response.

Operation ID: getAdminRunners

register 

register(*, description: str | None = None, ephemeral: bool | None = None, name: str) -> RegisterRunnerResponse

Register a new global runner.

Parameters:

Name Type Description Default
description str | None

Description of the runner to register.

 None
ephemeral bool | None

Register as ephemeral runner https://forgejo.org/docs/latest/admin/actions/security/#ephemeral-runner

 None
name str

Name of the runner to register. The name of the runner does not have to be unique.

 required

Returns:

Type Description
RegisterRunnerResponse

RegisterRunnerResponse contains the details of the just registered runner.

Raises:

Type Description
BadRequestError
  1. APIError is error format response.
UnauthorizedError
  1. APIUnauthorizedError is a unauthorized error response.
NotFoundError
  1. APINotFound is a not found error response.

Operation ID: registerAdminRunner

registration_token 

registration_token() -> RegistrationToken

Get a runner registration token for registering global runners.

This operation has been deprecated in Forgejo 15. Use the web UI or /admin/actions/runners instead.

Returns:

Type Description
RegistrationToken

RegistrationToken is a string used to register a runner with a server.
Deprecated

Deprecated in the vendored Spec; generated for compatibility.

Operation ID: adminGetRunnerRegistrationToken