Skip to main content
Version: 1.28-dev

Gitea Runner

This page will introduce the Gitea Runner, which is the runner for Gitea Actions.

tip

For detailed installation, configuration, and usage instructions, see the Gitea Runner documentation.

Obtain a registration token​

You can register a runner at different levels. It can be:

  • Instance level: The runner will run jobs for all repositories in the instance.
  • Organization level: The runner will run jobs for all repositories in the organization.
  • Repository level: The runner will run jobs for the repository it belongs to.

Note that the repository may still use instance-level or organization-level runners even if it has its own repository-level runners. A future release may provide an option to allow more control over this.

Before registering the runner and running it, you need a registration token. The level of the runner determines where to obtain the registration token.

  • Instance level: The admin settings page, like <your_gitea.com>/-/admin/actions/runners.
  • Organization level: The organization settings page, like <your_gitea.com>/<org>/settings/actions/runners.
  • Repository level: The repository settings page, like <your_gitea.com>/<owner>/<repo>/settings/actions/runners.

If you cannot see the settings page, please make sure that you have the right permissions and that Actions have been enabled.

The format of the registration token is a random string D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx.

A registration token can also be obtained from the Gitea command-line interface:

gitea --config /etc/gitea/app.ini actions generate-runner-token

You can also use GITEA_RUNNER_REGISTRATION_TOKEN/GITEA_RUNNER_REGISTRATION_TOKEN_FILE environment variables to set a global runner registration token when Gitea starts, for example:

openssl rand -hex 24 > /some-dir/runner-token
export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
./gitea --config ...

The token from the environment is valid until you reset the token (re-create a new one) via the web UI or API.

Tokens are valid for registering multiple runners, until they are revoked and replaced by a new token using the token reset link in the web interface.

Once you have a registration token, follow the Gitea Runner documentation to install, configure, and run your runner.