Skip to content

Latest commit

 

History

History
96 lines (62 loc) · 5.37 KB

README.md

File metadata and controls

96 lines (62 loc) · 5.37 KB
Raw

github-runner

GoDoc Quay Workflow Sponsors Mastodon

github-runner provides the GitHub Actions self-hosted runner as a container image that registers itself with GitHub.

Features

  • Minimalist, runners register themselves (no controller, no CRDs)
  • Acts as a GitHub App to generate registration tokens
  • Add org-level runners
  • Use github-runner as a base image to customize
    • Install languages needed for GitHub Workflows
    • Add tools needed for GitHub Workflows
  • Deregisters runner when the container/pod exits

Background

GitHub self-hosted runners allow you to run GitHub Actions Workflows in environments you manage on your own infrastructure.

github-runner packages the GitHub runner along with a tool to fetch a runner registration token dynamically on container start by acting as a GitHub App. On Kubernetes, you can create a Deployment of github-runner (or descendant image) Pods, watch them register and run jobs. A runner Pod can run one job ("ephemeral") or be long-lived.

Note: GitHub personal access tokens can also fetch runner registration tokens, but at most organizations, using a personal token or a robot user isn't an option.

Usage

Create a GitHub App for your account or organization. Use the links below to pre-fill fields where possible. Be sure to choose a unique app name (e.g. org-name/github-runner).

Organization Permissions:

  • Self-hosted runners (read/write)

Note the App ID.

Next, generate a private key.

Finally, install your private GitHub App into your user or organization.

Note the Install ID found at the end of the URL.

Create a Kubernetes Deployment (or similar definition) to run the quay.io/poseidon/github-runner (or derivative) container image with the following required environment variables (see configuration):

  • GH_APP_ID
  • GH_APP_KEY_PATH
  • GH_INSTALL_ID
  • GH_ORG

Typically GH_APP_KEY_PATH would be a path to a mounted Kubernetes Secret.

Finally, check that the runner(s) registered as Org Runners with GitHub.

Configuration

Configure github-runner to act as a GitHub App to obtain a self-hosted runner registration token.

env variable description
GH_APP_ID GitHub App ID
GH_APP_KEY_PATH Path to GitHub App key .pem
GH_INSTALL_ID GitHub Installation ID
GH_ORG GitHub organization name
GROUP Runner group defaults to default
LABELS Labels in addition to default: 'self-hosted,Linux,X64'
EPHEMERAL Unregister a runner after a job

Tradeoffs

github-runner is minimalist and low maintenance.

  • Runners registers themselves to GitHub (no controllers, CRDs, etc.)
  • Manage runners using ordinary Kubernetes manifests
  • Scale by scaling replicas (e.g. Kubernetes Deployment)
  • Customize by using github-runner as a base image (e.g. FROM)

More complex needs may be handled by more complex projects (out of scope):

  • Auto-scaling runners

Security

GitHub recommends self-hosted runners should only be used with private repositories at your own organization, since they run code inside your infrastructure. Additionally, github-runner allows runners to conveniently register themselves by acting as a GitHub App, meaning it may be possible for a workload to obtain the same GitHub App permissions (which allow managing self-hosted workers). Compared to other automation platforms, GitHub runners are pretty reasonable.