matt13290/action-runner repository overview

GitHub Actions Self-Hosted Runner (Guaranteed Cleanup)

This Docker image provides a secure and reliable self-hosted runner for GitHub Actions, built on a minimal Ubuntu base. It is configured to handle its entire lifecycle automatically, ensuring your GitHub Actions settings remain clean by removing the runner upon container shutdown.

Key Components

1. The Deployment (docker-compose.yml)

The docker-compose.yml file is the orchestration layer responsible for securely deploying and managing the container's lifecycle.

Image Specification: It points to the built image (matt13290/action-runner:linux-x64-2.329.0).

Secrets Injection (env_file): It uses the env_file: .env.runner directive to securely load the sensitive variables into the container environment at runtime. This is the core security feature for handling secrets.

Cleanup Trigger: By managing the container's shutdown, it initiates the automatic cleanup process defined in the entrypoint script.

version: '3.8'
services:
  action-runner:
    # Use the image tag you built (e.g., after running the build command)
    image: matt13290/action-runner:linux-x64-2.329.0
    container_name: action-runner
    # This line securely loads the URL, TOKEN, GROUP, and LABELS at runtime
    env_file: .env.runner
    # Ensures the runner restarts automatically if it crashes
    restart: always

1. The Runtime (.env.runner)

All sensitive data and configuration options are passed at runtime, ensuring the built image remains generic and secure.

Secrets Management: The required URL and TOKEN are loaded from the private .env.runner file via docker-compose.yml's env_file directive. These secrets never exist within the image layers.

Configuration: Custom labels and runner group are defined here, allowing flexible job targeting.

# GitHub URL (Organization or Repository URL)
URL=[https://github.com/Your-Org-Name](https://github.com/Your-Org-Name)

# FRESH Registration Token (required only for initial startup)
TOKEN=<YOUR_FRESH_GITHUB_RUNNER_TOKEN>

# Runner Configuration
RUNNER_GROUP=Default
LABELS=linux,self-hosted,my-custom-label

Usage Summary

To use this image, you must provide a valid .env.runner file and deploy using docker compose up -d. To cleanly remove the runner from GitHub, simply run docker compose down.