GH Actions误将合并分支识别为refs/heads别名，触发环境保护规则报错

问题描述 #

我遇到一个异常问题：GitHub Actions会将特性分支合并到staging分支的操作识别为refs/heads别名，从而触发环境保护规则导致执行失败。

复现步骤 #

git pull origin <branchName> locally
git branch -b feature/featureBranchName
git push origin feature/featureBranchName

# 提交PR将feature/featureBranchName合并到<branchName>（如staging）

报错信息 #

Branch <feature/featureBranchName> is not allowed to deploy to <branchName> due to environment protection rules.

原因分析 #

这个问题的核心是GitHub Actions在处理PR合并时，错误地将触发工作流的分支识别为特性分支，而非目标分支（比如staging）。当你给目标分支配置了环境保护规则（比如限制仅特定分支可部署到对应环境），Actions会误判发起合并的特性分支是部署源，从而触发规则拦截。

常见诱因包括：

• 工作流触发条件配置不当，比如用on: push或on: pull_request的默认设置，导致PR合并时以特性分支上下文执行工作流
• 部署动作（Action）在获取分支信息时，错误读取了GITHUB_HEAD_REF（特性分支）而非GITHUB_BASE_REF/GITHUB_REF（目标分支）

解决方法 #

1. 修正工作流触发条件 #

如果工作流是在PR合并到目标分支后执行，明确限定触发分支为目标分支：

on:
  push:
    branches:
      - staging  # 替换为你的目标分支名

如果需要在PR合并时触发，确保仅在合并成功后运行，并明确检出目标分支：

on:
  pull_request:
    types: [closed]
    branches:
      - staging
jobs:
  deploy:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4
        with:
          ref: staging  # 明确拉取目标分支代码

2. 修正分支上下文读取 #

在部署步骤中，确保使用正确的环境变量获取目标分支：

• 合并后的push事件：用${{ github.ref_name }}（对应目标分支）
• PR合并事件：用${{ github.event.pull_request.base.ref }}（目标分支）
  避免使用${{ github.head_ref }}（特性分支）作为部署分支的标识。

3. 调整环境保护规则（可选，不推荐降低安全性） #

如果需要保留PR触发的方式，可在环境保护规则中添加允许项：

• 开启“允许来自受保护分支的合并”选项
• 将特性分支前缀（如feature/*）加入允许部署的分支列表（此操作会降低环境安全性，谨慎使用）

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