在Github Actions构建过程中为Docker镜像添加Git标签与版本信息

核心思路 #

通过GitHub Actions内置环境变量+Docker构建参数，把版本信息注入到镜像标签、LABEL元数据或容器环境变量中，方便后续追踪镜像来源。

步骤1：在Dockerfile中预留版本信息注入点 #

修改你的Dockerfile，添加构建参数并将其转为镜像元数据或环境变量：

# 定义接收外部传入的构建参数
ARG RELEASE_TAG
ARG COMMIT_HASH
ARG COMMIT_MESSAGE

# 将参数设置为容器环境变量，运行时可直接查看
ENV RELEASE_TAG=${RELEASE_TAG}
ENV COMMIT_HASH=${COMMIT_HASH}
ENV COMMIT_MESSAGE=${COMMIT_MESSAGE}

# 把版本信息写入镜像LABEL，外部通过docker inspect即可查看
LABEL org.opencontainers.image.version=${RELEASE_TAG}
LABEL org.opencontainers.image.revision=${COMMIT_HASH}
LABEL org.opencontainers.image.notes="Commit: ${COMMIT_MESSAGE}"

步骤2：在GitHub Actions工作流中传递参数并构建镜像 #

编写或修改.github/workflows/docker-build.yml，利用GitHub内置变量和命令获取所需信息，传递给Docker构建命令：

name: 构建并推送Docker镜像
on:
  push:
    tags:
      - 'v*' # 仅当推送形如v1.0.0的Release Tag时触发工作流

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码
        uses: actions/checkout@v4
        with:
          fetch-depth: 1 # 仅拉取最新提交，减少耗时

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

      - name: 登录Docker仓库
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_TOKEN }}

      - name: 获取Commit Message
        id: get-commit-msg
        run: echo "COMMIT_MSG=$(git log -1 --pretty=%s)" >> $GITHUB_OUTPUT
        # 用%s只取Commit标题，避免换行/特殊字符导致构建失败，如需完整信息替换为%B

      - name: 构建并推送镜像
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          # 给镜像打多个标签：Release Tag + 短Commit Hash
          tags: |
            你的仓库名/镜像名:${{ github.ref_name }}
            你的仓库名/镜像名:${{ github.sha::7 }}
          # 传递构建参数到Dockerfile
          build-args: |
            RELEASE_TAG=${{ github.ref_name }}
            COMMIT_HASH=${{ github.sha::7 }}
            COMMIT_MESSAGE=${{ steps.get-commit-msg.outputs.COMMIT_MSG }}

补充说明 #

1. 非Tag触发场景适配：如果是分支构建（比如main分支），可以把RELEASE_TAG设为分支名（${{ github.ref_name }}），或者自定义为${{ github.ref_name }}-snapshot标识快照版本
2. 信息验证：构建完成后，可通过以下命令查看版本信息：
   • 查看镜像LABEL：docker inspect 你的镜像名:标签 | grep -A 5 "Labels"
   • 进入容器查看环境变量：docker run --rm 你的镜像名:标签 env | grep -E "RELEASE_TAG|COMMIT_HASH|COMMIT_MESSAGE"
3. 特殊字符处理：如果Commit Message包含特殊字符（如引号、换行），建议用git log -1 --pretty=%s只取标题部分，避免构建参数解析错误

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