Manage Runners
Documentation menu

GitHub setup

Create a fine-grained personal access token, choose a repository or organization and labels, and connect GitHub Actions self-hosted runners on GitHub.com.

Manage Runners registers each server as GitHub Actions self-hosted runners of one repository or one organization on GitHub.com. You give it a fine-grained personal access token for that repository or organization; it uses the token to register the servers and to remove them from GitHub again, so you decide in GitHub what the runner can reach and which workflows use it.

Repository or organization

Choose the scope under GitHub > Scope when you create the runner. It cannot be changed later.

  • Repository: enter the Owner, a GitHub user or organization, and the Repository. The runner takes jobs of that repository only.
  • Organization: enter the Organization and, optionally, a Runner group. Left empty, the runner joins the organization’s default runner group. The runner takes jobs of the organization’s repositories that the runner group allows, so you control access in the group’s settings in GitHub. Enter the name of a group that exists in the organization.

GitHub’s documentation describes runner groups and their repository access: Managing access to self-hosted runners using groups.

Create a fine-grained personal access token

  1. In GitHub, go to Settings > Developer settings > Personal access tokens > Fine-grained tokens and select Generate new token. The dashboard links to this page from the token field.

  2. Under Resource owner, choose the repository owner or the organization.

  3. Grant exactly one permission:

    Scope Repository access Permission
    Repository Only select repositories, with the runner’s repository Repository permission Administration: Read and write
    Organization not needed Organization permission Self-hosted runners: Read and write
  4. Choose an expiration, generate the token and copy it. It starts with github_pat_.

  5. Paste it into GitHub fine-grained personal access token in Manage Runners.

If your organization requires approval for fine-grained personal access tokens, an organization owner has to approve the token before it can register runners.

Manage Runners stores the token encrypted and never shows it again. It does not put the token on the server: for every new server, it asks GitHub for a registration token, which expires after an hour, and the server registers with that.

How the token is checked

When you create a runner, and when you save a new token or a change that recreates an active runner’s server, Manage Runners first asks GitHub for a registration token, which needs the same permission as registering. If GitHub refuses this check, nothing is created or changed and the form shows why:

Refusal Cause
GitHub rejected the token The token is mistyped, expired or revoked.
The token needs the repository permission “Administration” … or the organization permission “Self-hosted runners” … The token lacks the permission in the table above.
The repository or organization was not found, or the token cannot access it The owner, repository or organization is wrong, the token’s resource owner is another account, or the repository is not selected in the token.
GitHub could not be reached, or its rate limit was reached Try again later.

GitHub can still refuse the token after this check, when the new server is about to be created, for example because the token was revoked in the meantime. During an edit, the old server is already deleted by then: the new settings are saved, the runner stays paused, and the dashboard and the CLI say so. Resuming a paused runner with a refused token also leaves it paused. In both cases, edit the runner to enter a token that GitHub accepts, or use runner update --github-token-env in the CLI, and then resume it.

The token stays in use after the runner is created. Manage Runners needs it for every new server (when you resume the runner, when an edit recreates the server, for burst runners) and to remove the runner from GitHub when it is paused or deleted. Registered runners keep taking jobs when the token expires, so replace it before it does: edit the runner and enter the new token. A new token alone does not recreate the server.

Labels

GitHub gives every self-hosted runner the default labels self-hosted, Linux and its architecture, X64 or ARM64. The labels you add to the runner in Manage Runners are registered with GitHub as well. A label can have at most 256 characters and no commas. On Hetzner, labels also become server labels, so they must be valid Hetzner labels, such as ci-runner or role=ci-runner. DigitalOcean droplets get no labels, but GitHub still registers them.

Give the runner a label of its own and use it in your workflows’ runs-on:

jobs:
  build:
    runs-on: [self-hosted, ci-runner]
    steps:
      - uses: actions/checkout@v4
      - run: echo "Running on my own runner"

A job that asks only for default labels can go to any of your self-hosted runners. It can also go to a runner that is pausing while it still runs a job: such a runner loses its own labels until it is removed, but keeps the default ones. Your own label avoids both, and burst runners get the same labels as their anchor.

Changing the labels of an active GitHub runner recreates its server, because GitHub stores them with the registration.

Concurrency and runner instances

A GitHub runner instance runs one job at a time, so the runner’s concurrency is the number of instances on its server: 1 to 32. Selecting a product sets it to twice the vCPU count, at most 32. Each instance appears in GitHub as its own self-hosted runner, named after the Manage Runners runner and its ID, for example build-01-mr812999368881481087-1, -2 and so on; with a concurrency of 1, the number is left out.

Jobs run directly on the server as the user github-runner, not in a container per job; there is no executor to choose. The user can use Docker, so container jobs, service containers and docker build work, and jobs have root-equivalent access to the server. The server is not a copy of GitHub’s hosted runner images: besides Docker Engine 29 with the Buildx and Compose plugins, it has Git, Git LFS, jq, unzip and zstd. Install other tools in your workflow or run the job in a container. The actions runner keeps itself up to date; the server updates Debian and Docker packages on its own. Caches are only for GitLab runners.

What Manage Runners registers and removes

When In GitHub
You create, resume or duplicate a runner, or an edit or Fix recreates its server The new server registers its instances with a fresh registration token. An instance replaces a runner of the same name, so a resumed runner reuses its entries.
You pause it with Pause after running jobs Idle instances are removed at once. An instance that is running a job loses its own labels and is removed once the job has finished. After at most one hour, the server is deleted anyway.
You pause it with Pause now The server is deleted at once. Its instances stay in GitHub as offline until the runner is resumed or deleted.
You delete the runner Its instances are removed from GitHub.
Autoscaling adds or removes a burst runner Burst runners register in the anchor’s repository or organization, runner group and labels, and are removed from GitHub when they are drained or deleted. See Autoscaling.
You change only the token or the name Nothing changes in GitHub. After a rename, the instances keep their old names until the runner gets a new server.

Instances can also stay in GitHub as offline if GitHub cannot be reached when a runner is deleted. GitHub removes self-hosted runners that have not connected for more than 14 days, and you can remove them yourself under the repository’s or organization’s Settings > Actions > Runners.

GitHub.com only

Manage Runners works with repositories and organizations on GitHub.com. It does not support GitHub Enterprise Server or GHE.com, and it does not register enterprise-level runners.

The actions runner only makes outgoing HTTPS connections, so a runner needs no incoming rules for GitHub. Outgoing, it needs the GitHub addresses listed in Communication requirements, the Debian and Docker package repositories, Manage Runners during setup and for metrics, and whatever your jobs reach. See Hetzner setup and DigitalOcean setup for firewalls.

When registration fails

A runner shows Registration Failed when its server was created but could not install the actions runner or register it with GitHub, for example because the download failed or the runner settings were refused on the server. A token that GitHub refuses before the server is created does not lead to this state; see How the token is checked.

  1. Check the token’s resource owner, repository access and permission, and the runner group.
  2. In the dashboard, select Fix on the runner. Enter a new token, or leave the field empty to keep the stored one.
  3. Select Recreate, or Save and recreate with a new token. Manage Runners recreates the server, which registers again.

The CLI and the API report this state as REGISTRATION_FAILED. If an Active runner gets no jobs, compare the labels in your workflow’s runs-on with the runner’s labels in GitHub, and for an organization runner check that its runner group allows the repository. See Troubleshooting for other problems.