GitHub Actions 非主分支 workflow_dispatch 触发指南

问题描述

当在 GitHub Actions 中开发工作流程时，一个常见的挑战是：如何在非默认分支（非 master 或 main）上测试和运行通过 workflow_dispatch 事件触发的工作流程。

用户发现 GitHub Actions 界面存在以下行为：

• Actions 标签页会根据最后执行的工作流程来切换分支显示
• "This workflow has a workflow_dispatch event trigger" 提示文本似乎总是来自主分支，不会随分支切换而变化
• 在非默认分支上的工作流程无法直接通过 UI 界面触发

解决方案

方法一：使用 GitHub CLI（推荐）

GitHub CLI (gh) 提供了直接从命令行运行工作流程的能力，无需通过 UI 界面。

# 列出所有可用的工作流程
gh workflow list

# 运行特定分支上的工作流程
gh workflow run "工作流程名称" --ref 分支名称

# 带参数运行工作流程
gh workflow run "工作流程名称" --ref 分支名称 -f 参数名=参数值

TIP

使用 CLI 方法前，需要确保工作流程已被 GitHub 识别。如果工作流程不在列表中，可以先使用方法二或方法三进行注册。

方法二：添加 pull_request 触发器临时注册

通过添加 pull_request 触发器并创建一次拉取请求来注册工作流程：

name: '我的工作流程'
on:
  workflow_dispatch:
    inputs:
      参数名:
        description: 参数描述
  pull_request:  # 添加此行临时注册工作流程

jobs:
  你的任务:
    runs-on: ubuntu-latest
    steps:
      - run: echo "工作流程执行中"

步骤：

1. 添加 pull_request 触发器
2. 创建拉取请求（无需合并）
3. 移除 pull_request 触发器
4. 现在可以通过 CLI 运行工作流程

方法三：添加 push 触发器临时注册

如果你不希望创建拉取请求，可以使用 push 触发器：

name: '我的工作流程'
on:
  workflow_dispatch:
    inputs:
      参数名:
        description: 参数描述
  push:  # 添加此行临时注册工作流程
    branches:
      - 你的分支名

jobs:
  你的任务:
    runs-on: ubuntu-latest
    steps:
      - run: echo "工作流程执行中"

步骤：

1. 添加 push 触发器并指定分支
2. 推送一次代码到远程分支
3. 移除 push 触发器
4. 现在工作流程已注册，可以通过 CLI 运行

重要提示

当使用 push 或 pull_request 触发器时，所有 workflow_dispatch 输入参数都会被设置为 null。需要为参数设置默认值：

env:
  参数名: ${{ inputs.参数名 || '默认值' }}

方法四：在主分支创建占位工作流程

在默认分支创建一个简单的工作流程文件，确保它出现在 Actions 标签页中：

name: 占位工作流程

on:
  workflow_dispatch:

jobs:
  占位任务:
    runs-on: ubuntu-latest
    steps:
      - run: echo "这是占位工作流程"

然后在功能分支开发实际的工作流程，通过 UI 选择从功能分支运行。

最佳实践总结

1. 开发阶段：使用 GitHub CLI 进行测试，最为灵活方便
2. 临时注册：根据需要选择 push 或 pull_request 方式进行一次性注册
3. 参数处理：始终为 workflow_dispatch 输入参数设置默认值
4. 清理工作：注册完成后及时移除临时触发器，避免意外执行

示例工作流程

name: 功能测试工作流程

on:
  workflow_dispatch:
    inputs:
      环境:
        description: 部署环境
        required: true
        default: staging
        type: choice
        options:
          - staging
          - production

env:
  部署环境: ${{ inputs.环境 || 'staging' }}

jobs:
  部署:
    runs-on: ubuntu-latest
    steps:
      - name: 检查代码
        uses: actions/checkout@v4
        
      - name: 显示部署环境
        run: echo "部署到 $环境环境"
        env:
          环境环境: ${{ env.部署环境 }}

通过上述方法，你可以有效地在非默认分支上开发、测试和运行 GitHub Actions 工作流程，提高开发效率的同时保持代码库的整洁。