All posts
Engineering

Scalable Custom GitHub Action Runners with River

Build a custom containerized GitHub Actions runner with pre-baked tooling, push it to your River workspace registry, and orchestrate on-demand scale-up and scale-down directly from your workflows.

River Team
October 18, 20266 min read
Scalable Custom GitHub Action Runners with River

Standard GitHub-hosted runners are convenient, but reinstalling heavy dependencies on every run adds minutes to your pipeline, and keeping dedicated self-hosted VMs idle 24/7 burns through compute budgets.

With River's container runtime, you can bake your entire toolchain—pip, node/npm, custom scripts, and the GitHub Actions runner agent—into a single Docker image. You create the container app once, keep it stopped at zero cost when idle, and wake it up on-demand inside your GitHub Actions workflow using river containers deploy and river containers stop.

Everything below runs against a River workspace (e.g. acme.river.li) and its private registry (acme-r.river.li). Before starting, make sure you have the River CLI installed (npm install -g @brian-bill/river) and authenticated (river auth login).


Part 1: One-Time Runner Setup

The first three steps are a one-time setup. You will build the custom runner image, push it to your workspace registry, register the container on River, and save the resulting Container ID to your GitHub Secrets.

1) Write the Dockerfile and entrypoint for the GitHub Action Runner

To connect a container to GitHub Actions, the image needs the official GitHub Actions runner binary plus an entrypoint script that exchanges a GitHub Personal Access Token (GH_PAT) for a short-lived registration token at startup.

Because this is a standard Dockerfile, you can pre-install python3/pip, nodejs/npm, and copy in any reusable scripts your team relies on so your CI jobs start with zero setup time.

Create Dockerfile:

FROM ubuntu:22.04
 
ENV DEBIAN_FRONTEND=noninteractive
ARG RUNNER_VERSION="2.320.0"
 
# 1. Install base dependencies, Python/pip, Node.js/npm, and jq
RUN apt-get update && apt-get install -y \
    curl \
    git \
    jq \
    ca-certificates \
    sudo \
    build-essential \
    libicu-dev \
    python3 \
    python3-pip \
    && curl -fsSL [https://deb.nodesource.com/setup_20.x](https://deb.nodesource.com/setup_20.x) | bash - \
    && apt-get install -y nodejs \
    && rm -rf /var/lib/apt/lists/*
 
# 2. Optional: Pre-install global npm/pip packages or copy reusable scripts
# COPY ./scripts /usr/local/bin/
# RUN chmod +x /usr/local/bin/*
# RUN pip3 install --no-cache-dir pytest requests && npm install -g pnpm typescript
 
# 3. Create a dedicated non-root user for the GitHub runner
RUN useradd -m -s /bin/bash runner && \
    usermod -aG sudo runner && \
    echo "%sudo ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
 
WORKDIR /home/runner/actions-runner
 
# 4. Download and extract the official GitHub Actions Runner (linux-x64)
RUN curl -o actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz -L \
    [https://github.com/actions/runner/releases/download/v$](https://github.com/actions/runner/releases/download/v$){RUNNER_VERSION}/actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz \
    && tar xzf ./actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz \
    && rm actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz \
    && ./bin/installdependencies.sh
 
COPY entrypoint.sh /home/runner/actions-runner/entrypoint.sh
RUN chmod +x /home/runner/actions-runner/entrypoint.sh && \
    chown -R runner:runner /home/runner
 
USER runner
 
ENTRYPOINT ["./entrypoint.sh"]

Next, create entrypoint.sh in the same directory. It reads GH_PAT and GH_REPO (e.g., owner/repo) from the container's environment, registers the runner with the river-runner label, and cleans up automatically when river containers stop sends a shutdown signal:

#!/usr/bin/env bash
set -e
 
if [ -z "$GH_PAT" ] || [ -z "$GH_REPO" ]; then
  echo "Error: GH_PAT and GH_REPO environment variables must be set."
  exit 1
fi
 
RUNNER_NAME="river-runner-$(hostname)"
 
echo "Requesting registration token for ${GH_REPO}..."
REG_TOKEN=$(curl -sX POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer ${GH_PAT}" \
  "[https://api.github.com/repos/$](https://api.github.com/repos/$){GH_REPO}/actions/runners/registration-token" | jq -r .token)
 
if [ -z "$REG_TOKEN" ] || [ "$REG_TOKEN" = "null" ]; then
  echo "Error: Failed to retrieve runner registration token. Verify GH_PAT permissions."
  exit 1
fi
 
./config.sh \
  --url "[https://github.com/$](https://github.com/$){GH_REPO}" \
  --token "${REG_TOKEN}" \
  --name "${RUNNER_NAME}" \
  --labels "self-hosted,Linux,X64,river-runner" \
  --work "_work" \
  --unattended \
  --replace
 
cleanup() {
  echo "Caught termination signal. Deregistering runner..."
  ./config.sh remove --unattended --token "${REG_TOKEN}" || true
}
trap 'cleanup; exit 130' INT
trap 'cleanup; exit 143' TERM
 
./run.sh & wait $!

Note on GH_PAT permissions: Generate a fine-grained Personal Access Token (with Administration: Read and write repository permission) or a classic PAT (with repo scope). Store this token in your repository's GitHub Secrets as GH_PAT alongside your River credentials.


2) Build and push the image to your internal River registry

Every River workspace includes a private OCI registry. Log in using your workspace slug and API key:

river containers registry
# registry endpoint: acme-r.river.li
# username: acme
 
echo "$RIVER_API_KEY" | docker login acme-r.river.li -u acme --password-stdin
# Login Succeeded

Build the runner image targeting linux/amd64 (River's runtime nodes are x86_64) and push it to your internal workspace registry:

docker build --platform linux/amd64 -t acme-r.river.li/gh-runner:latest .
docker image inspect acme-r.river.li/gh-runner:latest --format '{{.Architecture}}'
# amd64
 
docker push acme-r.river.li/gh-runner:latest

3) Create the container, deploy, and store the Container ID in GitHub Secrets

Create the container app on River, passing your GH_PAT and GH_REPO as environment variables:

river containers create \
  --name gh-runner \
  --image acme-r.river.li/gh-runner:latest \
  --source registry \
  --env '{"GH_PAT":"ghp_your_personal_access_token","GH_REPO":"acme/my-repo"}'
# ✓ Container app created

Fetch the newly created container's ID and test an initial deploy:

river containers list
# ID        NAME       STATUS   IMAGE
# 971bedbc  gh-runner  created  acme-r.river.li/gh-runner:latest
 
river containers deploy 971bedbc

Once you confirm the runner registers under Settings → Actions → Runners in your GitHub repository, stop it so it stays scaled to zero until a workflow needs it:

river containers stop 971bedbc

Now copy your container ID (971bedbc) and configure the following GitHub Repository Secrets (Settings → Secrets and variables → Actions):

SecretValue
CONTAINERYour River container ID (e.g. 971bedbc)
GH_PATYour GitHub Personal Access Token (ghp_... or github_pat_...)
RIVER_WORKSPACEYour workspace ID (e.g. acme)
RIVER_API_KEYYour River API key (rqk_...)

Part 2: GitHub Action Workflow Setup (Scale Up, Run, Scale Down)

With the one-time setup complete, your GitHub Actions workflow can wake the runner container on demand, execute your custom pipeline steps using the tools baked into the image, and stop the container immediately afterward—even if a build or test step fails.

Create .github/workflows/on-demand-runner.yml:

name: CI with On-Demand River Runner
 
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:
 
jobs:
  scale-up:
    runs-on: ubuntu-latest
    steps:
      - name: Install River CLI
        run: npm install -g @brian-bill/river
 
      - name: Scale up custom runner container
        env:
          RIVER_WORKSPACE: ${{ secrets.RIVER_WORKSPACE }}
          RIVER_API_KEY: ${{ secrets.RIVER_API_KEY }}
        run: |
          river --workspace "$RIVER_WORKSPACE" --api-key "$RIVER_API_KEY" \
            containers deploy ${{ secrets.CONTAINER }}
 
  execute-pipeline:
    needs: scale-up
    runs-on: [self-hosted, Linux, X64, river-runner]
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
 
      - name: Verify pre-baked tools (Node, npm, Python, pip)
        run: |
          node --version
          npm --version
          python3 --version
          pip3 --version
 
      - name: Run custom build, test, or automation scripts
        env:
          GH_PAT: ${{ secrets.GH_PAT }}
        run: |
          # Add your custom workflow steps here:
          # npm ci && npm test
          # pip3 install -r requirements.txt && pytest
          # /usr/local/bin/my-reusable-script.sh
          echo "Running job on custom River container runner!"
 
  scale-down:
    needs: [scale-up, execute-pipeline]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - name: Install River CLI
        run: npm install -g @brian-bill/river
 
      - name: Scale down custom runner container to zero
        env:
          RIVER_WORKSPACE: ${{ secrets.RIVER_WORKSPACE }}
          RIVER_API_KEY: ${{ secrets.RIVER_API_KEY }}
        run: |
          river --workspace "$RIVER_WORKSPACE" --api-key "$RIVER_API_KEY" \
            containers stop ${{ secrets.CONTAINER }}

How the workflow operates

  1. a. Scale up (scale-up): Triggers river containers deploy ${{ secrets.CONTAINER }}. River boots your pre-built runner image (acme-r.river.li/gh-runner:latest), which immediately authenticates with GitHub using GH_PAT and listens for waiting jobs.
  2. b. Custom user steps (execute-pipeline): Targets runs-on: [self-hosted, Linux, X64, river-runner]. As soon as the River container comes online, GitHub dispatches this job into your container where pip, node/npm, and your custom scripts are already installed and ready.
  3. c. Scale down (scale-down): Configured with if: always() and needs: [scale-up, execute-pipeline] so it executes regardless of whether your tests pass or fail. Running river containers stop ${{ secrets.CONTAINER }} terminates the container and returns your runner compute footprint to zero until the next push.
containersgithub-actionsci-cddocker

Enjoyed this post?

Read more from the blog