Self Hosted GitHub Runners

A self-hosted runner is a system that you deploy and manage to execute jobs from GitHub Actions on This can be useful for

To use self-hosted runners, you will need to be an administrator of the GitHub project. If you can access /settings/actions/runners then you have the right access permissions.

GitHub Settings Runners

Create Self-Hosted Runner

You can get instructions on how to add a self-hosted actions runner from the settings page (change the organization/project information in the URL below to your organization/project).

GitHub Setup Runner Code

Please refer to the latest self-hosted action runner setup instructions directly from GitHub, what follows is a (slightly modified) copy of the those scripts on the /settings/actions/runners/new page.

Download the tools

Download the actions-runner code from GitHub, please refer to /settings/actions/runners/new for the latest URLs and checksum value.

mkdir -p /opt/actions-runner
(cd /opt/actions-runner && \
 curl -o actions-runner-linux-x64-2.293.0.tar.gz -L && \
 echo "06d62d551b686239a47d73e99a557d87e0e4fa62bdddcf1d74d4e6b2521f8c10  actions-runner-linux-x64-2.293.0.tar.gz" | shasum -a 256 -c && \
 tar xzf ./actions-runner-linux-x64-2.293.0.tar.gz)

Note that any service that you want to run on the self-hosted runner must be accessible via githubrunner group. For example, to run docker commands, you will need to modify the docker user as follows

usermod -aG docker githubrunner

A helper script has been created (and tested on a Linux x64 server) to help you setup your self-hosted runner. Copy and execute /tools/github_runner/ on your self-hosted server.

Or, you can run this directly on your server

/bin/bash -c "$(curl -fsSL"

If the installation above worked, you should be able to run

cd /opt/githubrunner && sudo -u githubrunner ./ --help

And see something similar to

 ./         Configures the runner
 ./ remove  Unconfigures the runner
 ./            Runs the runner interactively. Does not require any options.

Configure Runner

Then we create the runner and start the configuration experience. The token information will be different. GitHub self-hosted runners should NOT be run as root. In our example below we are using a githubrunner user (to create that user, you can run useradd githubrunner). If you are running in a docker environment, you probably also want to add them to the docker group (to add that group, you can run usermod -aG docker githubrunner).

sudo -u githubrunner ./ \
  --unattended \
  --url \
  --name passdemo \
  --runnergroup default \
  --labels passdemo \
  --work pass-docker \

And you will want the runner as a service, which is configured with

./ install githubrunner

If you want to run it locally, then just run


If you already configured a runner (i.e. the above fails), you can remove it with

sudo -u githubrunner ./ remove --token $GITHUB_RUNNER_TOKEN

View Runner via UI

If everything is configured correctly, then you should see the runners (assumes admin user)

Passdemo runner on

View Runners via API

You can query this information via GitHub’s Self-Hosted Runner APIs

To run the API calls you will need a Personal Access Token PAT stored in an environment variable

export GITHUB_TOKEN=ghp_abc123def456abc123def456abc123def456

If you configured the above correctly, you should now see the self-hosted runner with via the API.

curl \
  -H "Accept: application/vnd.github.v3+json" \
  -H "Authorization: token $GITHUB_TOKEN" \