使用Docker部署的Shell执行器GitLab Runner构建Docker镜像提示命令不存在怎么办

问题根因 #

报错本质是Docker部署的GitLab Runner容器内部未预装Docker客户端，Shell执行器会直接在容器内部的系统环境执行命令，因此找不到docker指令。

解决方案 #

方案一：挂载宿主机Docker环境（推荐，无需修改镜像）

直接复用宿主机已有的Docker服务，配置成本最低，操作步骤如下：

• 停止并删除原有GitLab Runner容器
• 启动容器时新增Docker相关挂载参数：

docker run -d \
  --name gitlab-runner \
  --restart always \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  # 挂载宿主机Docker二进制文件
  -v /usr/bin/docker:/usr/bin/docker \
  # 挂载Docker服务套接字，用于调用Docker引擎
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

• 配置访问权限：
  默认容器内的gitlab-runner用户无权限访问docker.sock，可任选以下一种方式授权：
  • 临时授权：进入容器执行chmod 666 /var/run/docker.sock
  • 永久授权：先查看宿主机docker组的GID（一般为998，可通过cat /etc/group | grep docker查看），进入容器后执行：

groupadd -g 替换为宿主机docker组GID docker
usermod -aG docker gitlab-runner

• 验证：进入容器执行docker version，能正常输出客户端和服务端版本信息即配置成功。

方案二：自定义内置Docker客户端的Runner镜像

如果需要和宿主机Docker版本解耦，可自行构建带Docker客户端的Runner镜像：

• 新建Dockerfile文件，内容如下：

FROM gitlab/gitlab-runner:latest
# 安装Docker官方客户端
RUN apt-get update && apt-get install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common && \
    curl -fsSL https://download.docker.com/linux/debian/gpg | apt-key add - && \
    add-apt-repository \
    "deb [arch=amd64] https://download.docker.com/linux/debian \
    $(lsb_release -cs) \
    stable" && \
    apt-get update && apt-get install -y docker-ce-cli && \
    rm -rf /var/lib/apt/lists/*

• 执行docker build -t custom-gitlab-runner .构建镜像，使用该镜像启动Runner即可，仍需挂载/var/run/docker.sock才能正常调用Docker服务。

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