如何在Google Cloud Build中结合cloudbuild.yaml与Dockerfile使用BRANCH_NAME

问题背景 #

此前使用Dockerfile和cloudbuild.yaml构建镜像正常，尝试在Dockerfile中引入BRANCH_NAME值后构建失败，报错invalid reference format。相关配置及错误日志如下：

原cloudbuild.yaml #

steps:
- name: 'gcr.io/cloud-builders/docker'
  env:
    - '$BRANCH_NAME=${_$BRANCH_NAME}'
  entrypoint: 'bash'
  args: ['-c', 'docker pull gcr.io/$PROJECT_ID/github.com/videoo-io/videoo-render-$BRANCH_NAME:latest || exit 0']
- name: 'gcr.io/cloud-builders/docker'
  env:
    - '$BRANCH_NAME=${_$BRANCH_NAME}'
  args: [
            'build',
            "--build-arg=ENV=$_BRANCH_NAME",
            '-t', 'gcr.io/$PROJECT_ID/github.com/videoo-io/videoo-render-$BRANCH_NAME:latest',
            '--cache-from', 'gcr.io/$PROJECT_ID/github.com/videoo-io/videoo-render-$BRANCH_NAME:latest',
            '.'
        ]
substitutions:
  _BRANCH_NAME: $BRANCH_NAME
options:
  dynamic_substitutions: true
images: ['gcr.io/$PROJECT_ID/github.com/videoo-io/videoo-render-$BRANCH_NAME:latest']
timeout: 7200s

原Dockerfile #

ARG  BRANCH_NAME=$_BRANCH_NAME

FROM --platform=amd64 gcr.io/videoo7/github.com/videoo-io/videoo-render-${BRANCH_NAME}:latest

EXPOSE 80
COPY . /app
WORKDIR /app
RUN cd /app && cmake . && make

# Define default command.
RUN chmod +x /app/entrypoint.sh
ENTRYPOINT ["/app/entrypoint.sh"]

失败构建日志 #

Step #0: a561219ed4f5: Pull complete
Step #0: Digest: sha256:09a3f79713e906ff0640bac04c9cb74523ee33e930afe8683f15f2cd5904fbc1
Step #0: Status: Downloaded newer image for gcr.io/videoo7/github.com/videoo-io/videoo-render-main:latest
Step #0: gcr.io/videoo7/github.com/videoo-io/videoo-render-main:latest
Finished Step #0
Starting Step #1
Step #1: Already have image (with digest): gcr.io/cloud-builders/docker
Step #1: Sending build context to Docker daemon  196.9MB

Step #1: Step 1/8 : ARG  BRANCH_NAME=$_BRANCH_NAME
Step #1: Step 2/8 : FROM --platform=amd64 gcr.io/videoo7/github.com/videoo-io/videoo-render-${BRANCH_NAME}:latest
Step #1: invalid reference format
Finished Step #1
ERROR
ERROR: build step 1 "gcr.io/cloud-builders/docker" failed: step exited with non-zero status: 1

错误原因 #

1. Dockerfile中ARG默认值无效：$_BRANCH_NAME是Cloud Build的自定义变量，Dockerfile无法直接识别，导致${BRANCH_NAME}为空，生成的镜像引用格式错误。
2. cloudbuild.yaml参数不匹配：传递的build-arg参数是ENV=$_BRANCH_NAME，但Dockerfile中声明的ARG是BRANCH_NAME，变量名不对应。
3. 冗余环境变量配置：Cloud Build内置的$BRANCH_NAME可直接使用，无需通过env字段重新定义，原写法$BRANCH_NAME=${_$BRANCH_NAME}存在语法错误。

修正方案 #

1. 修改cloudbuild.yaml #

移除冗余配置，确保参数传递正确：

steps:
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: 'bash'
  args: ['-c', 'docker pull gcr.io/$PROJECT_ID/github.com/videoo-io/videoo-render-$BRANCH_NAME:latest || exit 0']
- name: 'gcr.io/cloud-builders/docker'
  args: [
            'build',
            "--build-arg=BRANCH_NAME=$BRANCH_NAME",
            '-t', 'gcr.io/$PROJECT_ID/github.com/videoo-io/videoo-render-$BRANCH_NAME:latest',
            '--cache-from', 'gcr.io/$PROJECT_ID/github.com/videoo-io/videoo-render-$BRANCH_NAME:latest',
            '.'
        ]
options:
  dynamic_substitutions: true
images: ['gcr.io/$PROJECT_ID/github.com/videoo-io/videoo-render-$BRANCH_NAME:latest']
timeout: 7200s

• 移除无效的env字段和自定义substitutions，直接使用Cloud Build内置的$BRANCH_NAME变量。
• 将build-arg参数名改为BRANCH_NAME，与Dockerfile中的ARG名称保持一致。

2. 修改Dockerfile #

调整ARG声明，确保FROM指令能正确获取变量：

# 声明ARG，接收来自build-arg的BRANCH_NAME值
ARG BRANCH_NAME

# 使用ARG变量指定基础镜像
FROM --platform=amd64 gcr.io/videoo7/github.com/videoo-io/videoo-render-${BRANCH_NAME}:latest

EXPOSE 80
COPY . /app
WORKDIR /app
RUN cd /app && cmake . && make

# Define default command.
RUN chmod +x /app/entrypoint.sh
ENTRYPOINT ["/app/entrypoint.sh"]

• 移除ARG的无效默认值$_BRANCH_NAME，避免Dockerfile上下文无法识别的变量。
• 确保ARG声明在FROM指令之前，保证变量能在FROM中被使用。

验证 #

重新触发Cloud Build构建，此时Dockerfile会正确接收来自cloudbuild.yaml传递的BRANCH_NAME值，生成有效的基础镜像引用，构建即可成功。

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