Simple Usage #

If you’d like to use a runner on a single machine, this page is for you.

Create a docker-compose.yml file with the following content.

services:
  runner:
    image: knatnetwork/github-runner:latest
    restart: always
    environment:
      RUNNER_REGISTER_TO: 'knatnetwork'
      RUNNER_LABELS: 'docker,knat'
      KMS_SERVER_ADDR: 'http://kms:3000'
      GOPROXY: 'http://goproxy.knat.network,https://proxy.golang.org,direct'
      ADDITIONAL_FLAGS: '--ephemeral'
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      - kms

  kms:
    image: knatnetwork/github-runner-kms:latest
    restart: always
    environment:
      PAT_knatnetwork: 'ghp_Lxxxxxxxxxx2NUk5F'
      PAT_rust-lang: 'ghp_Lxxxxxxxxxx2NUk5F'

If your org’s name is org_name, the KMS environment variable is PAT_org_name: 'ghp_Lxxxxxxxxxx2NUk5F'.

Then run docker-compose up -d. The runner registers on the knatnetwork org.

Notes:

• To run the runner without Docker support, delete the volumes block.
• To keep the runner after a job finishes, remove ADDITIONAL_FLAGS: '--ephemeral'. See GitHub Actions: Ephemeral self-hosted runners & new webhooks for auto-scaling.
• Even with --ephemeral, restarting the container after a job does not clean the environment thoroughly, so the next job on the same worker can hit leftover state. See github-runner#2.
• To register a runner to one repository, set RUNNER_REGISTER_TO to <org_name>/<repo_name> and keep PAT_<org_name> on the KMS container.

Environment #