Ephemeral, root self-hosted GitHub Actions runners using Podman

Deploy ephemeral, rootless GitHub Actions runners using Podman with automated token management and resource allocation. Runners execute in isolated containers with tmpfs mounts for security and state isolation. Includes Python, Node.js, Rust, and standard CI tools. Perfect if you want secure, stateless self-hosted runners without root privileges.

Prerequisites

• Podman: For rootless container execution.
• GitHub CLI (gh): To fetch runner registration tokens.
  • You must authenticate first: gh auth login
• jq: To parse the token JSON response from the GitHub API.

Setup

1. Copy the example environment file:

   cp .env.example .env

2. (Optional) Set your default target repository in .env:

   GITHUB_REPO=your-user/your-repo

   Note: Real runner tokens will be written to .env automatically when the deployment script runs. This file is ignored by git.

Usage

The deploy_runner.sh script automates fetching tokens via the GitHub API, building the Podman image, and running the container(s).

Basic Deployment

Deploy a single runner for a specific repository:

./deploy_runner.sh -r owner/repo

If you configured GITHUB_REPO in your .env, you can omit the -r flag:

./deploy_runner.sh

Multiple Runners

You can deploy multiple runners for the same repository simultaneously by specifying the -n flag. The script will automatically calculate CPU and RAM limits to distribute your host's resources evenly among them.

# Deploy 4 runners
./deploy_runner.sh -n 4 -r owner/repo

How It Works

1. Token Retrieval: The script uses gh api to fetch ephemeral runner registration tokens.
2. Container Build: A custom Ubuntu-based image is built containing Node.js, Python, Rust, and other CI tools (defined in Containerfile).
3. Rootless Execution: podman creates the runner instances in rootless mode with limited privileges.
4. Ephemeral Configuration: When a container starts, entrypoint.sh initializes the runner config using --ephemeral, ensuring it only runs one job before unregistering and exiting. The container's restart policy automatically spins it back up to fetch the next job.