Skip to main content

Hathora Runners for Github Actions

This guide will help you set up self-hosted GitHub runners using Hathora’s bare metal and cloud infrastructure, enabling you to run your CI/CD workloads on dedicated hardware for more control, performance, and cost-efficiency.

Update your GitHub workflow​

To use self-hosted runners, you need to update your GitHub Actions workflow.

  1. Open your .github/workflows/
  2. Change the runs-on value to hathora 
    jobs:
    build:
        runs-on: hathora
        steps:
        - uses: actions/checkout@v2
        - name: Run build script
            run: ./build.sh

This tells GitHub to assign jobs to your Hathora fleet instead of using GitHub-hosted runners.

Set up your Hathora account​

  1. Go to console.hathora.dev and create an account.
  2. Once logged in, create a new Application.
    • You can name it something like github-runners (the name is for your reference only) App name

Select the Hathora runner build image​

Hathora provides a pre-built public image for GitHub runners.

  1. Select External Registry
  2. Specify the Image name as hathora/github-actions-runner and URL as ghcr.io External registry This image enables your deployed processes to communicate with GitHub and register as self-hosted runners.

Configure your resource profile​

You’ll need to specify the hardware requirements for each runner.Choose a CPU:Memory configuration suitable for the tasks your runners will execute. CPU Memory If you're unsure, start with a smaller profile and increase as needed.

Set required environment variables​

Set the following Environment Variables in your deployment configuration:

  1. GITHUB_ORG = your GitHub organization name
  2. GITHUB_TOKEN = a Personal Access Token with appropriate permissions to register and run runners
  3. GITHUB_ADDITIONAL_LABELS = optionally add custom labels to your runners CPU Memory

Deploy and configure runner availability​

  1. Click Create deployment to launch your GitHub runners on Hathora’s infrastructure
  2. After deployment, navigate to the Settings page for your application
  3. In Advanced Settings at the bottom, expand the Static Process Allocation section. Expand static process allocation
  4. Set the Target to the number of runners you want to be available. Static process allocation
tip

If you're using our bare metal capacity, we recommend setting the Target number of runners equal to how many runners can fit on your bare metal node in that region. This ensures that all of your bare metal capacity is fully utilized.