在非 master 分支运行 GitHub Actions

GitHub Actions 默认只在主分支（通常为 master 或 main）上读取并执行工作流文件。本文将介绍如何在不同分支上正确配置和触发 GitHub Actions。

问题分析

当您在其他分支创建或修改 GitHub Actions 工作流文件时，可能会发现这些工作流没有被触发执行。这是因为 GitHub 的机制决定的：

官方文档说明

根据 GitHub Actions 官方文档，工作流触发过程如下：

1. 仓库中发生事件，生成带有相关提交 SHA 和 Git 引用的事件 webhook
2. 在对应的提交 SHA 或 Git 引用中搜索 .github/workflows 目录
3. 只有在相同分支上存在工作流文件时，才会触发对应的工作流

这意味着工作流文件必须存在于触发事件所在的分支上。

解决方案

方法一：在目标分支创建 workflows 目录

最直接的解决方案是在您需要运行 Actions 的分支上创建 .github/workflows 目录，并放入您的 YAML 工作流文件。

# .github/workflows/your-workflow.yaml
name: Your Workflow

on:
  push:
    branches: ["your-branch-name"]
  
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    # 这里添加您的构建步骤

TIP

确保工作流文件中的 branches 配置与您当前使用的分支名称相匹配。

方法二：使用 workflow_dispatch 手动触发

如果您希望能够手动触发工作流，可以添加 workflow_dispatch 触发器：

on:
  push:
    branches: ["your-branch-name"]
  workflow_dispatch:
    inputs:
      environment:
        description: '部署环境'
        required: true
        default: 'staging'

添加后，您可以在 GitHub 的 Actions 标签页中手动选择分支并运行工作流。

方法三：通过路径过滤触发条件

通过配置路径过滤，确保只有在特定文件发生变化时才触发工作流：

on:
  push:
    branches: ["your-branch-name"]
    paths:
      - 'src/**'           # src 目录下的任何变化
      - 'package.json'     # package.json 文件变化
      - 'Dockerfile'       # Dockerfile 变化

方法四：跨分支工作流配置

如果您希望在特定分支上测试工作流，但最终要合并到主分支，可以使用以下配置：

on:
  push:
    branches:
      - "feature/**"     # 所有特性分支
      - "develop"        # 开发分支
      - "main"           # 主分支
  pull_request:
    branches:
      - "main"

具体操作步骤

1. 在目标分支创建工作流文件

   git checkout your-branch
   mkdir -p .github/workflows
   touch .github/workflows/your-workflow.yaml

2. 编写工作流配置 参考上述解决方案中的示例编写适合您需求的 YAML 文件。

3. 提交并推送更改

   git add .github/workflows/your-workflow.yaml
   git commit -m "添加 GitHub Actions 工作流"
   git push origin your-branch

4. 验证工作流执行 在 GitHub 仓库的 Actions 标签页中查看工作流是否被触发执行。

注意事项

重要提示

• 确保工作流文件中的分支名称与您实际使用的分支完全匹配（大小写敏感）
• 如果使用路径过滤，请确保包含所有可能触发构建的相关文件路径
• 首次在分支上设置工作流时，需要执行一次推送操作才能激活

总结

通过正确配置分支触发条件和合理使用工作流触发器，您可以在任何分支上成功运行 GitHub Actions。关键是要确保工作流文件存在于目标分支上，并且触发条件与您的开发和部署流程相匹配。

选择适合您团队工作流程的方法，可以让 GitHub Actions 在分支开发、功能测试和持续集成场景中发挥最大效用。