Github Actions如何为各分支生成起始为1的独立构建编号

问题背景 #

现有GitHub Actions内置变量无法满足分支独立计数需求：

• ${{ github.run_attempt }}：仅手动重跑时递增，推送代码时始终返回1
• ${{ github.run_number }}：全仓库分支共享计数，手动触发时不递增

需要实现：每个分支的触发（推送/手动）计数独立递增，最终用于生成Docker镜像标签（格式：docker-reg-host/project-name/branch-name:branch_run_number-run_attempt）

方法一：仓库文件维护分支计数 #

通过在仓库中存储JSON文件记录各分支的触发次数，每次工作流运行时读取、递增并提交更新。

实现步骤 #

1. 初始化计数文件
   在仓库根目录创建.branch-runs.json，初始内容：

{}

2. 工作流配置示例

on:
  push:
    branches: [main, feature1, feature2]
  workflow_dispatch:

jobs:
  build-and-tag:
    # 避免因提交计数文件触发循环
    if: github.actor != 'github-actions[bot]'
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 需要完整Git历史用于提交

      - name: 计算分支触发次数
        id: calc-run-num
        run: |
          BRANCH_NAME="${GITHUB_REF#refs/heads/}"
          # 读取当前分支的已有计数，无记录则设为0
          CURRENT_COUNT=$(jq -r ".\"$BRANCH_NAME\" // 0" .branch-runs.json)
          NEW_COUNT=$((CURRENT_COUNT + 1))
          # 更新JSON文件
          jq ".\"$BRANCH_NAME\" = $NEW_COUNT" .branch-runs.json > temp.json && mv temp.json .branch-runs.json
          # 输出变量供后续步骤使用
          echo "branch_run_number=$NEW_COUNT" >> "$GITHUB_OUTPUT"
          echo "run_attempt=${{ github.run_attempt }}" >> "$GITHUB_OUTPUT"

      - name: 提交计数更新
        run: |
          git config --global user.name "GitHub Actions Bot"
          git config --global user.email "actions@github.com"
          git add .branch-runs.json
          git commit -m "Update run count for ${{ github.ref_name }} to ${{ steps.calc-run-num.outputs.branch_run_number }}"
          git push
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: 构建并推送Docker镜像
        run: |
          IMAGE_TAG="${{ steps.calc-run-num.outputs.branch_run_number }}-${{ steps.calc-run-num.outputs.run_attempt }}"
          docker build -t "docker-reg-host/project-name/${{ github.ref_name }}:$IMAGE_TAG" .
          docker push "docker-reg-host/project-name/${{ github.ref_name }}:$IMAGE_TAG"

注意事项 #

• 依赖jq工具（Ubuntu-latest runner默认预装）
• 默认GITHUB_TOKEN具备仓库写入权限，需通过if条件避免循环触发工作流

方法二：通过GitHub API查询分支运行次数 #

利用GitHub API查询当前分支的工作流运行总数，以此作为分支触发计数。

工作流配置示例 #

on:
  push:
    branches: [main, feature1, feature2]
  workflow_dispatch:

jobs:
  build-and-tag:
    runs-on: ubuntu-latest
    steps:
      - name: 查询分支触发次数
        id: get-run-num
        run: |
          BRANCH_NAME="${GITHUB_REF#refs/heads/}"
          # 查询当前分支已完成的工作流运行总数（可根据需求调整status参数）
          RUN_COUNT=$(curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
            "https://api.github.com/repos/${{ github.repository }}/actions/runs?branch=$BRANCH_NAME&status=completed" \
            | jq '.total_count')
          # 下一次运行的编号为总数+1
          NEW_COUNT=$((RUN_COUNT + 1))
          echo "branch_run_number=$NEW_COUNT" >> "$GITHUB_OUTPUT"
          echo "run_attempt=${{ github.run_attempt }}" >> "$GITHUB_OUTPUT"

      - name: 构建并推送Docker镜像
        run: |
          IMAGE_TAG="${{ steps.get-run-num.outputs.branch_run_number }}-${{ steps.get-run-num.outputs.run_attempt }}"
          docker build -t "docker-reg-host/project-name/${{ github.ref_name }}:$IMAGE_TAG" .
          docker push "docker-reg-host/project-name/${{ github.ref_name }}:$IMAGE_TAG"

注意事项 #

• 若需统计特定工作流，可在API地址中添加工作流ID：/actions/workflows/<WORKFLOW_ID>/runs
• 注意GitHub API速率限制：使用GITHUB_TOKEN时，仓库级请求上限为1000次/小时，足够日常使用
• status参数可取值completed、in_progress、queued，按需调整统计范围

方法对比 #

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