如何在GitHub Actions的publish.yaml中用Docker Compose CLI为镜像打标加标注

一、解决动态标签和Labels的核心问题 #

docker compose build确实不支持直接传--tag和--label参数，但可以通过环境变量注入的方式，在不修改原始docker-compose.yml的前提下，动态传递这些值。

1. 给docker-compose.yml加变量引用 #

在你的docker-compose.yml里，给目标服务的image和labels字段加上环境变量占位符，不用硬写固定值：

services:
  your-service-name:
    build: .
    image: ghcr.io/你的用户名/你的仓库名:${IMAGE_TAG}
    labels:
      ${IMAGE_LABELS}

2. 在GitHub Actions中传递动态值 #

在.github/workflows/publish.yaml里，先通过docker/metadata-action提取tags和labels，再把它们转换成Compose能识别的环境变量：

jobs:
  build-n-push:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码
        uses: actions/checkout@v4

      - name: 初始化Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: 登录GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: 提取Docker元数据
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/你的用户名/你的仓库名
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=sha

      - name: 准备Compose环境变量
        run: |
          # 从元数据的tags里取第一个作为镜像标签（按需调整）
          echo "IMAGE_TAG=$(echo '${{ steps.meta.outputs.tags }}' | cut -d',' -f1 | awk -F':' '{print $2}')" >> $GITHUB_ENV
          # 把逗号分隔的labels转换成换行格式，适配Compose的labels字段
          echo "IMAGE_LABELS=$(echo '${{ steps.meta.outputs.labels }}' | tr ',' '\n')" >> $GITHUB_ENV

      - name: 用Compose构建镜像
        run: docker compose build

      - name: 推送镜像到GHCR
        run: docker compose push

二、更简洁的替代方案：直接用docker/build-push-action #

如果你的Compose构建逻辑不复杂（比如没有多服务依赖、复杂的volume挂载等），可以直接抛弃docker compose build，改用docker/build-push-action@v4，把Compose里的build配置转移到这个action里，直接用元数据的tags和labels：

- name: 构建并推送镜像
        uses: docker/build-push-action@v4
        with:
          context: .  # 和Compose里的build.context一致
          file: ./Dockerfile  # 和Compose里的build.dockerfile一致
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          # 如果原来Compose里有build.args，在这里添加
          build-args: |
            ENV=prod
            VERSION=${{ steps.meta.outputs.version }}

这种方式更直接，不需要折腾Compose的变量，适合单服务镜像构建场景。

三、Labels的注意事项 #

用Compose方案时，docker/metadata-action输出的labels是逗号分隔的key=value字符串，通过tr ',' '\n'转换成换行后，Compose会自动解析为每个独立的label。如果遇到包含逗号或特殊字符的label，需要用printf做转义处理，比如：

echo "IMAGE_LABELS=$(printf "%s\n" "${{ steps.meta.outputs.labels }}" | sed 's/,/\\n/g')" >> $GITHUB_ENV

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