Skip to content

Heata Runners: Client Onboarding Guide

Overview

Heata Runners are hosted GitHub Actions runners that execute your CI/CD workflows on Heata's infrastructure. Your jobs run in fully isolated, ephemeral runners that are created fresh for every job and destroyed immediately after.

Switching to heata takes about 10 minutes. Switching back to your previous set up takes just a few minutes.

Prerequisites

  • A GitHub organisation (Free, Team, or Enterprise plan)
  • Admin access to the organisation
  • One or more repositories with GitHub Actions workflows
  • Your runner label prefix (provided by Heata during onboarding)

Step 1: Install the Heata Runner App

  1. Go to https://github.com/apps/heata-runners/installations/new
  2. Select your GitHub organisation
  3. Choose which repositories the App can access:
  4. All repositories if you want all repos to be able to use Heata runners
  5. Only select repositories if you want to start with specific repos
  6. Click Install
  7. After installation, you'll be redirected to a page with a URL like: https://github.com/organizations/yourorg/settings/installations/12345678 Send the number at the end of this URL (your installation ID) to your Heata contact. We need it to connect your runners.

That's it. No API keys, no SSH keys, no tokens to manage. The GitHub App handles all authentication automatically.

What permissions does the App need?

The Heata Runner App requires: - Actions: Read-only (to see when workflows are queued) - Self-hosted runners: Read & write (to register ephemeral runners for your org)

The App does not have access to your code, secrets, issues, pull requests, or any other repository content. It can only manage runner registrations.

Step 2: Update your workflow files

Change the runs-on value in your workflow files from a GitHub-hosted runner to a Heata runner.

jobs:
  build:
    runs-on: yourprefix-heata-standard
    steps:
      - uses: actions/checkout@v4
      - run: npm install
      - run: npm test

Replace yourprefix with the label prefix we provided during onboarding.

Available runner sizes

For simplicity of getting started we provide three tiers. If you have specific needs, please talk to us about custom configurations.

Tier vCPU RAM Storage Price/Min GitHub Equiv. Savings Ideal Use Case
heata Slim 2 5 GB 30 GB £0.0007 ubuntu-slim ~53% Linting, small unit tests, and lightweight automation
heata Standard 4 8 GB 50 GB £0.0030 ubuntu-latest ~32% Docker builds and heavy integration tests
heata Large 8 32 GB 100 GB £0.0059 linux-4-core ~34% Large-scale data processing and monolithic builds

Every tier offers double the vCPU compared to the equivalent GitHub-hosted runner. heata Large also doubles the RAM versus GitHub's 4-core runner.

Examples:

runs-on: yourprefix-heata-slim       # lightweight jobs
runs-on: yourprefix-heata-standard   # recommended — general purpose
runs-on: yourprefix-heata-large      # resource-intensive jobs

You can use different sizes for different jobs in the same workflow:

jobs:
  lint:
    runs-on: yourprefix-heata-slim
    steps:
      - uses: actions/checkout@v4
      - run: npm run lint

  build:
    runs-on: yourprefix-heata-large
    steps:
      - uses: actions/checkout@v4
      - run: npm run build

  test:
    runs-on: yourprefix-heata-standard
    steps:
      - uses: actions/checkout@v4
      - run: npm test

Step 3: Push and verify

  1. Commit and push the updated workflow file
  2. Go to the Actions tab in your repository
  3. You should see your workflow running on a Heata runner
  4. The runner name will appear as something like heata-runner-a3f8 in the job log

The first runs may take longer than usual while first downloads occur. Subsequent runs benefit from warm caches and should be faster.

That's it

There is no step 4. Your workflows now run on Heata's low-carbon infrastructure.

Optional: Faster caching

Heata runners include a high-speed local cache service on the same physical machine as your runners. To take advantage of it, you can replace actions/cache with our cache action:

Before

- uses: actions/cache@v4
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

After

- uses: heata-run/cache@v1
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

This is a drop-in replacement. Same syntax, same parameters. The difference is that cache data is stored on local storage rather than GitHub's servers, making cache save/restore significantly faster and with no 10 GB size limit.

Note: The standard actions/cache still works on Heata runners. Our cache action is an optional performance upgrade, not a requirement.

Switching back to GitHub-hosted runners

If you ever need to switch back, change runs-on back to a GitHub-hosted runner:

runs-on: ubuntu-latest

That's the only change needed. There are no dependencies, lock-in, or cleanup steps. Your workflows are standard GitHub Actions and work identically on any runner.

Pre-installed software

Heata runners come with the following pre-installed:

  • OS: Ubuntu 24.04 LTS
  • Docker: Docker Engine + Docker Compose + Buildx
  • Node.js: Latest LTS (via nvm)
  • Python: 3.11+ with pip
  • Go: Latest stable
  • Java: OpenJDK 17
  • Build tools: make, cmake, gcc, g++
  • CLI tools: git, curl, wget, jq, zip, unzip, gh (GitHub CLI)

Need something else? Additional tools can be installed in your workflow using standard apt-get, npm install -g, pip install, etc. - or let us know if you'd like something added to the base image.

FAQ

How are my workflows kept secure?

Each client's runners operate within their own dedicated, isolated virtual machine, fully separated from all other clients. Within that VM, every job gets a fresh, ephemeral runner that is: - Created from a clean image for each job - Completely destroyed after the job finishes - Unable to access any other client's workloads or data

Your secrets are injected by GitHub directly into the runner, just like with GitHub-hosted runners. Heata never has access to your repository secrets.

Can I use this across multiple repos?

Yes. When you install the GitHub App, you choose which repositories can use Heata runners. Any workflow in those repos can use your yourprefix-heata-* labels. No per-repo setup is needed.

What happens if a runner goes down mid-job?

GitHub will mark the job as failed, and you can re-run it from the Actions tab. The Heata orchestrator automatically cleans up the runner. This is the same behaviour as GitHub-hosted runners.

Is there a concurrency limit?

Yes, your organisation has a configurable maximum number of concurrent runners. Speak to your Heata contact to adjust this. Jobs that exceed the limit are queued and will start as soon as a slot becomes available.

How fast do runners start?

Runners typically boot and are ready to pick up a job within 15-30 seconds of the workflow being triggered. Subsequent runs benefit from local Docker image caching, package manager caching, and warm build caches.

Can I keep using some workflows on GitHub-hosted runners?

Absolutely. You can mix and match. Some jobs can use runs-on: ubuntu-latest (GitHub-hosted) while others use runs-on: yourprefix-heata-standard (Heata) in the same workflow file.

What regions are runners available in?

Heata runners are hosted in the UK and can be used from anywhere in the world. GitHub Actions traffic routes over GitHub's own network, so your workflows will work regardless of where your team is located.

Support

If you have questions or run into issues:

  • Email: techsupport@heata.co
  • Slack: We can set up a shared channel with your team
  • Response time: Within 4 business hours for production issues