在 GitHub Actions 中获取当前分支

1. 概述

在编写 GitHub Actions 自动化流程时，动态获取当前分支名是一项常见且关键的需求。无论是自动化部署、运行测试，还是根据分支执行不同逻辑，都需要在工作流中准确识别分支信息。

尤其在多分支开发流程中，不同分支可能代表不同阶段，如 feature 分支、staging 分支、production 分支，此时根据分支名做出不同响应尤为重要。

本文将介绍如何在 GitHub Actions 中正确获取当前分支名，涵盖：

• GitHub 内置的上下文（context）机制
• push 与 pull request 事件中分支识别的差异
• 实际示例代码及操作演示

---

2. 理解 GitHub 上下文（Context）

GitHub Actions 提供了一系列内置的上下文对象，用于在工作流执行期间获取运行时信息。这些上下文包括：

• github：包含仓库、事件类型、分支等信息
• env：环境变量
• job：当前任务的 ID、状态等信息

其中，**github 是我们获取分支信息的关键上下文**。我们可以通过它访问触发事件的分支、标签、提交信息等。

2.1. github 上下文详解

github 上下文提供了触发事件的完整上下文信息。其中：

• github.ref：表示触发事件的引用（ref），如分支或标签名
• github.head_ref：仅在 pull request 事件中使用，表示源分支名
• github.event_name：表示当前事件类型（如 push、pull_request）

2.2. github.ref 示例

github.ref 的格式通常是：

refs/heads/<branch-name>

例如，当你在 main 分支上 push 提交时，github.ref 的值为：

refs/heads/main

我们通常通过字符串处理提取出 main，例如使用 Bash 的字符串截取：

${GITHUB_REF##*/}

这样就可以直接获取分支名。

---

3. 使用 github.ref 获取分支名

在 GitHub Actions 中，github.ref 会被自动转换为环境变量 GITHUB_REF，因此你可以在 shell 脚本中直接使用它。

3.1. push 与 pull request 事件中的区别

事件类型	获取分支的方式	示例值
push	GITHUB_REF	refs/heads/main
pull request	github.head_ref	feature-branch

⚠️ 注意：在 pull request 事件中，GITHUB_REF 通常指向目标分支（即 base 分支），而源分支信息需要使用 github.head_ref 获取。

3.2. 提取分支名的方法

在 Bash 中，可以使用如下方式提取：

${GITHUB_REF##*/}

这将去掉 refs/heads/ 前缀，只保留分支名。

---

4. 获取当前分支名的实战示例

4.1. 在 push 事件中获取分支名

创建 .github/workflows/push-branch-name.yml 文件：

name: Print Branch Name on Push

on:
  push:
    branches:
      - "*"

jobs:
  print-branch-name:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Print branch name
        run: |
          echo "Current branch: ${GITHUB_REF##*/}"

✅ 说明：

• 该工作流监听所有分支的 push 事件
• 使用 ${GITHUB_REF##*/} 提取并打印分支名

4.2. 在 pull request 事件中获取源分支名

创建 .github/workflows/pull-request-branch-name.yml 文件：

name: Print Branch Name on Pull Request

on:
  pull_request:
    branches:
      - "*"

jobs:
  print-branch-name:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Print source branch name
        run: |
          echo "Source branch: ${{ github.head_ref }}"

✅ 说明：

• 该工作流监听所有 pull request 事件
• 使用 github.head_ref 获取源分支名并打印

4.3. 同时支持 push 与 pull request 的统一处理

创建 .github/workflows/push-and-pr.yml 文件：

name: Print Branch Name On Push and Pull Requests

on:
  push:
    branches:
      - "*"
  pull_request:
    branches:
      - "*"

jobs:
  print-branch-name:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Get branch name
        id: get-branch-name
        run: |
          if [ "${{ github.event_name }}" == "pull_request" ]; then
            echo "BRANCH_NAME=${{ github.head_ref }}" >> $GITHUB_OUTPUT
          else
            echo "BRANCH_NAME=${GITHUB_REF##*/}" >> $GITHUB_OUTPUT
          fi
        shell: bash

      - name: Print branch name
        run: |
          echo "Branch name: ${{ steps.get-branch-name.outputs.BRANCH_NAME }}"

✅ 说明：

• 使用 github.event_name 判断事件类型
• 动态选择 github.head_ref 或 GITHUB_REF 提取分支名
• 使用 GITHUB_OUTPUT 设置输出变量，便于后续步骤复用

---

5. 总结

本文介绍了如何在 GitHub Actions 中获取当前分支名，重点包括：

• 使用 github.ref 和 github.head_ref 区分 push 和 pull request 场景
• 使用 Bash 字符串处理提取分支名
• 编写支持多事件类型的工作流

✅ 推荐实践：

• 在多分支部署流程中，使用分支名控制部署目标或运行策略
• 对于 pull request，务必使用 github.head_ref 获取源分支，避免误判 base 分支

完整代码示例可在 GitHub 仓库 获取。

---