derskythe/github-runner

令牌范围

创建用于自托管运行器的GitHub个人访问令牌（PAT）时，请确保选择以下范围：

• repo（全部）
• admin:org（全部）（组织级运行器必需）
• admin:enterprise（全部）（企业级运行器必需）
• admin:public_key - read:public_key
• admin:repo_hook - read:repo_hook
• admin:org_hook
• notifications
• workflow

Systemd服务配置

以下是Systemd服务定义示例：

shell
# 安装方法：
#   sudo install -m 644 ephemeral-github-actions-runner.service /etc/systemd/system/
#   sudo systemctl daemon-reload
#   sudo systemctl enable ephemeral-github-actions-runner
# 启动方法：
#   sudo systemctl start ephemeral-github-actions-runner
# 停止方法：
#   sudo systemctl stop ephemeral-github-actions-runner
# 查看实时日志：
#   journalctl -f -u ephemeral-github-actions-runner.service --no-hostname --no-tail
[Unit]
Description=临时GitHub Actions运行器容器
After=docker.service
Requires=docker.service

[Service]
TimeoutStartSec=0
Restart=always
ExecStartPre=-/usr/bin/docker stop %N
ExecStartPre=-/usr/bin/docker rm %N
ExecStartPre=-/usr/bin/docker pull derskythe/github-runner:latest
ExecStart=/usr/bin/docker run --rm \
  --env-file /etc/ephemeral-github-actions-runner.env \
  -e RUNNER_NAME=%H \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --name %N \
  derskythe/github-runner:latest

[Install]
WantedBy=multi-user.target

对应的环境变量文件示例：

pwsh
# sudo install -m 600 ephemeral-github-actions-runner.env /etc/
RUNNER_SCOPE=repo
REPO_URL=https://github.com/your-org/your-repo
# 组织范围的替代配置：
# RUNNER_SCOPE=org
# ORG_NAME=your-org
LABELS=any-custom-labels-go-here
ACCESS_TOKEN=foo-access-token
RUNNER_WORKDIR=/tmp/runner/work
DISABLE_AUTO_UPDATE=1
EPHEMERAL=1

临时运行器

GitHub托管的运行器是完全临时的。您可以删除其所有数据而不会影响未来的作业。

要在自托管运行器中实现相同的弹性：

1. 在容器环境中设置 EPHEMERAL=1
2. 不要将本地文件夹挂载到 RUNNER_WORKDIR（确保无文件系统持久化）
3. 使用 --rm 运行容器（终止后删除容器）
4. 将容器执行包装在系统服务中，使其自动重启（每个作业后启动新容器）

非Root运行器

本项目默认以 root 用户运行容器。

非root运行是支持的非默认行为，通过环境变量 RUN_AS_ROOT 控制。默认值为 true。

• 若为 true：保留旧行为，以root运行
• 若为 true 且通过 -u（或任何编排工具等效参数）指定用户：报错并退出
• 若为 false：以root运行容器，并通过gosu切换到 runner 用户
• 若为 false 且通过 -u（或任何编排工具等效参数）指定用户：以指定用户运行整个容器

运行器用户为 runner，UID为 1001，GID为 121

如果要以非root用户运行整个容器：

• 将环境变量 RUN_AS_ROOT 设置为 false
• 确保 RUNNER_WORKDIR 未提供（默认 /_work）或权限正确。runner 用户无法在入口点脚本中更改其无权访问的目录权限
• 在docker命令中添加 -u runner 或 -u 1001。在k8s中，这对应 securityContext.runAsUser。Nomad等工具配置方式不同。

Actions工作流示例

yaml
name: 打包
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: self-hosted
    steps:
    - uses: actions/checkout@v4
    - name: 构建包
      run: make all

Docker Compose配置

yaml
version: '2.3'
services:
  worker:
    image: derskythe/github-runner:latest
    environment:
      REPO_URL: https://github.com/example/repo
      RUNNER_NAME: example-name
      RUNNER_TOKEN: someGithubTokenHere
      RUNNER_WORKDIR: /tmp/runner/work
      RUNNER_GROUP: my-group
      RUNNER_SCOPE: 'repo'
      LABELS: linux,x64,gpu
    security_opt:
      # SELinux系统需要此选项以允许容器管理其他容器
      - label:disable
    volumes:
      - '/var/run/docker.sock:/var/run/docker.sock'
      - '/tmp/runner:/tmp/runner'
      # 注意：Docker-in-Docker的一个特点是，此路径在主机和容器内必须相同，
      # Docker管理命令在容器外运行，但期望使用容器内的路径

Nomad配置

terraform
job "github_runner" {
    datacenters = ["home"]
    type = "system"
    task "runner" {
        driver = "docker"
        env {
            ACCESS_TOKEN       = "footoken"
            RUNNER_NAME_PREFIX = "myrunner"
            RUNNER_WORKDIR     = "/tmp/github-runner-your-repo"
            RUNNER_GROUP       = "my-group"
            RUNNER_SCOPE       = "org"
            ORG_NAME           = "octokode"
            LABELS             = "my-label,other-label"
        }
        config {
            image = "myoung34/github-runner:latest"

            privileged  = true
            userns_mode = "host"
            volumes = [
                "/var/run/docker.sock:/var/run/docker.sock",
                "/tmp/github-runner-your-repo:/tmp/github-runner-your-repo",
            ]
        }
    }
}

Kubernetes配置

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: actions-runner
  namespace: runners
spec:
  replicas: 1
  selector:
    matchLabels:
      app: actions-runner
  template:
    metadata:
      labels:
        app: actions-runner
    spec:
      volumes:
      - name: dockersock
        hostPath:
          path: /var/run/docker.sock
      - name: workdir
        hostPath:
          path: /tmp/github-runner-your-repo
      containers:
      - name: runner
        image: derskythe/github-runner:latest
        env:
        - name: ACCESS_TOKEN
          value: foo-access-token
        - name: RUNNER_SCOPE
          value: "org"
        - name: ORG_NAME
          value: octokode
        - name: LABELS
          value: my-label,other-label
        - name: RUNNER_TOKEN
          value: footoken
        - name: REPO_URL
          value: https://github.com/your-account/your-repo
        - name: RUNNER_NAME_PREFIX
          value: foo
        - name: RUNNER_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: RUNNER_WORKDIR
          value: /tmp/github-runner-your-repo
        - name: RUNNER_GROUP
          value: my-group
        volumeMounts:
        - name: dockersock
          mountPath: /var/run/docker.sock
        - name: workdir
          mountPath: /tmp/github-runner-your-repo

Bash示例

自动获取令牌

如果提供了 ACCESS_TOKEN（GitHub个人访问令牌），运行器令牌可以在运行时自动获取。这使用https://developer.github.com/v3/actions/self_hosted_runners/#create-a-registration-token%E3%80%82%E4%BE%8B%E5%A6%82%EF%BC%9A

pwsh
docker run -d --restart always --name github-runner \
  -e ACCESS_TOKEN="footoken" \
  -e RUNNER_NAME="foo-runner" \
  -e RUNNER_WORKDIR="/tmp/github-runner-your-repo" \
  -e RUNNER_GROUP="my-group" \
  -e RUNNER_SCOPE="org" \
  -e ORG_NAME="octokode" \
  -e LABELS="my-label,other-label" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/github-runner-your-repo:/tmp/github-runner-your-repo \
  derskythe/github-runner:latest

企业范围运行器

pwsh
docker run -d --restart always --name github-runner \
  -e ACCESS_TOKEN="footoken" \
  -e RUNNER_NAME="foo-runner" \
  -e RUNNER_WORKDIR="/tmp/github-runner-your-repo" \
  -e RUNNER_GROUP="my-group" \
  -e RUNNER_SCOPE="enterprise" \
  -e ENTERPRISE_NAME="my-enterprise" \
  -e LABELS="my-label,other-label" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/github-runner-your-repo:/tmp/github-runner-your-repo \
  derskythe/github-runner:latest

组织运行器

pwsh
docker run -d --restart always --name github-runner \
  -e RUNNER_NAME_PREFIX="myrunner" \
  -e ACCESS_TOKEN="footoken" \
  -e RUNNER_WORKDIR="/tmp/github-runner-your-repo" \
  -e RUNNER_GROUP="my-group" \
  -e RUNNER_SCOPE="org" \
  -e DISABLE_AUTO_UPDATE="true" \
  -e ORG_NAME="octokode" \
  -e LABELS="my-label,other-label" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/github-runner-your-repo:/tmp/github-runner-your-repo \
  derskythe/github-runner:latest

仓库运行器

pwsh
docker run -d --restart always --name github-runner \
  -e REPO_URL="https://github.com/username/repo" \
  -e RUNNER_NAME="foo-runner" \
  -e RUNNER_TOKEN="footoken" \
  -e RUNNER_WORKDIR="/tmp/github-runner-your-repo" \
  -e RUNNER_GROUP="my-group" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/github-runner-your-repo:/tmp/github-runner-your-repo \
  derskythe/github-runner:latest

Shell包装器

pwsh
function github-runner {
name=github-runner-${1//\//-}
org=$(dirname $1)
repo=$(basename $1)
tag=${3:-latest}
docker rm -f $name
docker run -d --restart=always \
-e REPO_URL="https://github.com/${org}/${repo}" \
-e RUNNER_TOKEN="$2" \
-e RUNNER_NAME="linux-${repo}" \
-e RUNNER_WORKDIR="/tmp/github-runner-${repo}" \
-e RUNNER_GROUP="my-group" \
-e LABELS="my-label,other-label" \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /tmp/github-runner-${repo}:/tmp/github-runner-${repo} \
--name $name derskythe/github-runner:latest
}
github-runner your-account/your-repo AARGHTHISISYOURGHACTIONSTOKEN
github-runner your-account/some-other-repo ARGHANOTHERGITHUBACTIONSTOKEN ubuntu-focal

重用配置

此方法可应用于所有其他部署方式

pwsh
# 仓库级运行器
docker run -d --restart always --name github-runner \
  -e REPO_URL="https://github.com/username/repo" \
  -e RUNNER_NAME="foo-runner" \
  -e RUNNER_TOKEN="footoken" \
  -e RUNNER_WORKDIR="/tmp/github-runner-your-repo" \
  -e RUNNER_GROUP="my-group" \
  -e CONFIGURED_ACTIONS_RUNNER_FILES_DIR="/actions-runner-files" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/github-runner-your-repo:/tmp/github-runner-your-repo \
  -v /tmp/foo:/actions-runner-files \
  derskythe/github-runner:latest

代理支持

要在代理服务器后运行GitHub运行器，需要将GitHub运行器https://docs.github.com/en/actions/hosting-your-own-runners/using-a-proxy-server-with-self-hosted-runners%E4%BD%9C%E4%B8%BA%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E4%BC%A0%E9%80%92