GitLab Runner Docker执行器报错docker-compose未找到，该如何处理？

我通过以下命令注册了GitLab Runner：

gitlab-runner register --non-interactive \
  --url ${URL} \
  --registration-token ${REGISTRATION_TOKEN} \
  --description ${RUNNER_NAME} \
  --tag-list ${TAGS} \
  --executor "docker" \
  --docker-image="docker:stable" \
  --docker-pull-policy if-not-present \
  --locked=false \
  --docker-privileged=true \
  --docker-volumes=["/var/run/docker.sock:/var/run/docker.sock", "/cache"]

对应的Runner配置文件config.toml内容如下：

[[runners]]
  name = "XXX"
  url = "XXX"
  id = 19981753
  token = "XXX"
  token_obtained_at = 2022-12-24T11:43:10Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "docker"
  [runners.custom_build_dir]
  [runners.cache]
    MaxUploadedArchiveSize = 0
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify = false
    image = "docker:stable"
    privileged = true
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"]
    pull_policy = ["if-not-present"]
    shm_size = 0

当运行包含docker-compose命令的CI流水线时，出现docker-compose: not found错误，相关.gitlab-ci.yml片段：

before_script:
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY

stages:
  - build
  - staging
  - release
  - deploy

build:
  stage: build
  script:
    - echo "IMAGE_APP_TAG=$STAGE_IMAGE_APP_TAG" >> .env
    - docker-compose build
    - docker-compose push
  only:
    - dev
    - main

请问应该使用什么Docker镜像来运行docker-compose？需要修改.gitlab-ci.yml还是GitLab Runner的config.toml？

问题根源 #

docker:stable官方镜像仅预装了Docker CLI，没有包含docker-compose工具，因此会出现命令找不到的错误。

可选解决方式 #

1. 修改.gitlab-ci.yml（推荐，灵活不影响其他流水线）

这种方式仅针对需要docker-compose的流水线生效，不会干扰其他使用该Runner的任务。

方式A：在流水线中临时安装docker-compose

在before_script里添加安装步骤：

before_script:
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  # 基于Alpine镜像安装docker-compose
  - apk add --no-cache docker-compose

方式B：更换为包含docker和docker-compose的镜像

直接使用官方预装两者的镜像，比如docker/compose:latest（指定具体版本号更稳定，例如docker/compose:2.20.2），可全局设置或针对单个job设置：

全局设置（所有job共用该镜像）：

image: docker/compose:latest

before_script:
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY

stages:
  - build
  - staging
  - release
  - deploy

build:
  stage: build
  script:
    - echo "IMAGE_APP_TAG=$STAGE_IMAGE_APP_TAG" >> .env
    - docker-compose build
    - docker-compose push
  only:
    - dev
    - main

单个job设置（仅build任务使用）：

before_script:
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY

stages:
  - build
  - staging
  - release
  - deploy

build:
  stage: build
  image: docker/compose:latest
  script:
    - echo "IMAGE_APP_TAG=$STAGE_IMAGE_APP_TAG" >> .env
    - docker-compose build
    - docker-compose push
  only:
    - dev
    - main

2. 修改GitLab Runner的config.toml（影响所有流水线）

如果所有使用该Runner的流水线都需要docker-compose，可修改Runner配置：

1. 找到config.toml中[runners.docker]下的image字段，将docker:stable替换为docker/compose:latest（或指定版本）：

[runners.docker]
  tls_verify = false
  image = "docker/compose:latest"  # 修改此处
  privileged = true
  # 其余配置保持不变

2. 重启GitLab Runner服务使配置生效：

gitlab-runner restart

内容的提问来源于stack exchange，提问作者Егор Климов