github-action-runner/README.md

GitHub Action Runners (Docker Compose)

Self-hosted GitHub Actions runners running in Docker, based on myoung34/docker-github-actions-runner.

Quick start

1. Create the data folder for your org

Each runner stores its work directory under data/<your-org-name>:

mkdir -p data/myorg

2. Get a GitHub access token

1. Go to https://github.com/settings/tokens (on your user account, not the org).
2. Click Generate new token (classic).
3. Name: something like github-self-hosted-runners.
4. Expiration: set to No expiration.
5. Check these scopes:
   • admin:org
   • admin:org_hook
   • notifications
   • read:public_key
   • read:repo_hook
   • repo
   • workflow
6. Generate and copy the token (it looks like ghp_XXXXXXXXXXXXXXXXXXXXXXXXXX).

3. Configure docker-compose.yml

Edit the service and set your values:

services:
  github-runner-myorg:
    image: git.neoh.ir/public/github-action-runner:latest
    #image: myoung34/github-runner:latest
    restart: unless-stopped
    container_name: github-runner-myorg
    privileged: true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data/myorg:/home/runner/work
    environment:
      DOCKER_HOST: unix:///var/run/docker.sock
      RUNNER_NAME: ghr-myorg
      RUNNER_GROUP: self-hosted
      RUNNER_SCOPE: org
      ORG_NAME: myorg
      LABELS: self-hosted,linux,docker,x64
      RUNNER_WORKDIR: /home/runner/work
      ACCESS_TOKEN: ghp_XXXXXXXXXXXXXXXXXXXXXXXXXX

Replace myorg with your org name and paste your token into ACCESS_TOKEN.

Important: RUNNER_GROUP must be self-hosted. The GitHub runner group name must match this value exactly (see step 4).

4. Create the runner group (name must be self-hosted)

The group name must be exactly self-hosted — it has to match RUNNER_GROUP: self-hosted in docker-compose.yml. Any other name will fail registration.

1. Go to https://github.com/organizations/myorg/settings/actions/runner-groups.
2. Create a new group and set Group name to self-hosted (exact spelling).
3. Repository access: select Selected repositories, then choose which repos may use this runner.
4. Optionally enable Allow public repositories if you need runners on public repos (security risk — read GitHub’s warning first).
5. Workflow access: select All workflows (or restrict to specific workflows if you prefer).

Replace myorg in the URL above with your actual org name.

5. Start the runner

docker compose up -d

With RUNNER_GROUP: self-hosted set, the runner registers into that group automatically. Confirm it under GitHub → Org → Settings → Actions → Runners (and under Runner groups → self-hosted).

If it landed in the Default group instead, open the runner and move it into self-hosted.

Useful commands

docker compose logs -f      # follow logs
docker compose down         # stop and remove
docker compose pull         # update the image

Adding more runners

Copy the service block, rename it (e.g. github-runner-otherorg), give it a unique container_name / RUNNER_NAME, point its volume at a new data/<org> folder, and create that folder with mkdir -p data/<org>.

Notes

• The runner group must be named self-hosted so it matches RUNNER_GROUP: self-hosted in docker-compose.yml.

• The default image is mirrored to git.neoh.ir/public/github-action-runner:latest. To re-mirror the upstream image (see cmd-to-push.txt):

  docker buildx imagetools create \
    --tag git.neoh.ir/public/github-action-runner:latest \
    myoung34/github-runner:latest
  

• Keep your ACCESS_TOKEN secret — don't commit it to a public repo.