GitHub Actions自托管Runner构建容器时Docker套接字权限拒绝问题

核心原因 #

宿主机器的/var/run/docker.sock权限归属于宿主的docker用户组，而Runner容器内默认的runner用户组GID，与宿主docker组的GID不匹配——即便在容器内将runner加入本地docker组，也无法匹配宿主socket的权限规则，最终导致构建时权限拒绝。

解决方案 #

1. 启动容器时直接绑定宿主docker组GID

先在宿主机器查询docker组的GID：

getent group docker | cut -d: -f3

假设输出为999，修改Runner容器启动命令，添加--group-add参数绑定该GID：

docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GITHUB_OWNER=<xxx> \
  -e GITHUB_REPOSITORY=<xxxx> \
  -e GITHUB_PAT=<xxxx> \
  --group-add $(getent group docker | cut -d: -f3) \
  <你的GitHub Actions Runner镜像名称>

此方法无需修改镜像文件，直接让容器内的runner用户加入宿主的docker组。

2. 修改entrypoint.sh适配宿主docker组GID

如果需要镜像具备通用性，可在entrypoint.sh中添加权限适配逻辑：

# 在启动Runner前执行权限适配
if [ -n "$DOCKER_GID" ]; then
  # 调整容器内docker组的GID与宿主一致
  groupmod -g "$DOCKER_GID" docker 2>/dev/null || groupadd -g "$DOCKER_GID" docker
  # 将runner用户加入该组
  usermod -aG docker runner
fi

# 执行原Runner启动命令
exec ./run.sh "$@"

同时在Dockerfile中确保entrypoint.sh拥有执行权限：

COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

启动容器时传入宿主docker组GID作为环境变量：

docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GITHUB_OWNER=<xxx> \
  -e GITHUB_REPOSITORY=<xxxx> \
  -e GITHUB_PAT=<xxxx> \
  -e DOCKER_GID=$(getent group docker | cut -d: -f3) \
  <你的GitHub Actions Runner镜像名称>

3. 临时调试方案（不推荐生产环境）

若需快速验证权限问题，可进入Runner容器直接修改socket权限：

# 进入运行中的Runner容器
docker exec -it <容器ID> bash
# 临时开放socket权限
chmod 666 /var/run/docker.sock

如果此时构建恢复正常，说明确实是组权限不匹配导致的问题，优先采用前两种方案彻底解决。

内容的提问来源于stack exchange，提问作者Donovin