juliansantosinfo/github-runner repository overview

⁠GitHub Actions Runner

Self-hosted GitHub Actions Runner packaged as a multi-arch Docker image based on Ubuntu 22.04, with built-in Docker CLI and Docker Compose Plugin support.

⁠Supported Platforms

⁠Quick Start

⁠Docker Compose (recommended)

Create a docker-compose.yml:

services:
  github-runner:
    image: juliansantosinfo/github-runner:latest
    environment:
      - GITHUB_PAT=<your-personal-access-token>
      - GITHUB_REPO_OWNER=<owner>
      - GITHUB_REPO_NAME=<repository>
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - github-runner-data:/actions-runner
    restart: always

volumes:
  github-runner-data:

Then run:

docker compose up -d

⁠Docker CLI

docker run -d \
  --name github-runner \
  -e GITHUB_PAT=<your-personal-access-token> \
  -e GITHUB_REPO_OWNER=<owner> \
  -e GITHUB_REPO_NAME=<repository> \
  -v /var/run/docker.sock:/var/run/docker.sock \
  juliansantosinfo/github-runner:latest

⁠Environment Variables

⁠How It Works

1. On startup, the container calls the GitHub API to obtain a registration token and registers itself as a self-hosted runner.
2. The runner is labeled with docker and linux automatically.
3. On container shutdown (SIGTERM / SIGINT), the runner unregisters itself from GitHub automatically.
4. Runner state is persisted in the /actions-runner volume so the container can restart without re-registering.

⁠Using the Runner in a Workflow

jobs:
  build:
    runs-on: [self-hosted, linux, docker]
    steps:
      - uses: actions/checkout@v4
      - run: docker compose version

⁠Runner Labels

⁠Image Details

⁠Source Code

github.com/juliansantosinfo/github-runner⁠

⁠License

MIT License⁠ © Julian Santos