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.

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_PATpermissions: Generate a fine-grained Personal Access Token (with Administration: Read and write repository permission) or a classic PAT (withreposcope). Store this token in your repository's GitHub Secrets asGH_PATalongside 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 SucceededBuild 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:latest3) 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 createdFetch 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 971bedbcOnce 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 971bedbcNow copy your container ID (971bedbc) and configure the following GitHub Repository Secrets (Settings → Secrets and variables → Actions):
| Secret | Value |
|---|---|
CONTAINER | Your River container ID (e.g. 971bedbc) |
GH_PAT | Your GitHub Personal Access Token (ghp_... or github_pat_...) |
RIVER_WORKSPACE | Your workspace ID (e.g. acme) |
RIVER_API_KEY | Your 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
- a. Scale up (
scale-up): Triggersriver containers deploy ${{ secrets.CONTAINER }}. River boots your pre-built runner image (acme-r.river.li/gh-runner:latest), which immediately authenticates with GitHub usingGH_PATand listens for waiting jobs. - b. Custom user steps (
execute-pipeline): Targetsruns-on: [self-hosted, Linux, X64, river-runner]. As soon as the River container comes online, GitHub dispatches this job into your container wherepip,node/npm, and your custom scripts are already installed and ready. - c. Scale down (
scale-down): Configured withif: always()andneeds: [scale-up, execute-pipeline]so it executes regardless of whether your tests pass or fail. Runningriver containers stop ${{ secrets.CONTAINER }}terminates the container and returns your runner compute footprint to zero until the next push.
Enjoyed this post?
Read more from the blog