跳到主要内容

配置触发条件

本文档介绍如何通过 on 字段配置工作流的触发事件，包括 push、pull_request、workflow_dispatch、schedule 以及分支/路径/标签过滤规则。

当你需要控制 workflow 在什么事件、什么分支、什么路径或什么 Tag 下触发时。

前提条件​

  • workflow 文件已放在 .gitcode/workflows/ 目录下。
  • 熟悉 YAML 基本语法。

快速示例​

name: ci

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  test:
    name: 测试
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - name: Checkout source code
      	uses: checkout
      - name: Run build and test
      	run: npm ci && npm test

配置说明​

push 触发​

push 事件在代码推送到仓库时触发：

on:
  push:
    branches:
      - main
      - develop

pull_request 触发​

pull_request 事件在创建、更新或合并 Pull Request 时触发。branches 过滤的是目标分支（base branch），而非源分支：

on:
  pull_request:
    branches:
      - main

重要：branches 过滤的是 PR 的目标分支（base branch），即 PR 合入的目标分支。如果 PR 的目标分支不在 branches 列表中，则不会触发。

pull_request 支持配置活动类型：

on:
  pull_request:
    types:
      - open
      - update
      - reopen
    branches:
      - main

types 取值范围： pull_request 的 types 取值范围为 [merge, open, reopen, update]。不填时默认为 [open, reopen, update]。

pull_request_comment 触发​

在 Pull Request 评论被创建、编辑、删除时触发。

on:
  pull_request_comment:
    types:
      - created
      - edited
      - deleted
    branches:
      - main
    comments:
      - '/deploy'
      - '/test'

事件类型：

类型说明
created评论创建
edited评论编辑
deleted评论删除

过滤字段：

字段说明示例
branches匹配 PR 目标分支名模式main, feature/**
comments基于正则表达式的评论内容过滤/deploy, /test

comments 过滤说明： comments 字段支持对评论内容基于正则表达式进行条件过滤，只有评论内容匹配指定正则模式的才会触发工作流。例如配置 comments: ['/deploy']，则只有评论中包含 /deploy 指令时才触发。

流水线回显结果： 通过评论PR触发流水线时，在流水线中配合使用associate-pr-comment插件，可以将流水线执行详情同步展示在PR评论区域下及PR检查页面。

修改为：“通过评论PR触发流水线时，在流水线中配合使用associate-pr-comment插件，可以将流水线执行详情同步展示在PR评论区域下及PR检查页面。

workflow_dispatch 手动触发​

workflow_dispatch 支持在 AtomGit 界面手动触发 workflow，可定义输入参数：

on:
  workflow_dispatch:
    inputs:
      environment:
        description: '部署目标环境'
        required: true
        default: 'staging'
        type: string
      version:
        description: "发布版本号"
        type: string
        required: false
        default: "1.0.0"
      deploy_count:
        description: '并行部署数量'
        type: string
        required: false
        default: "1"
      dry_run:
        description: '是否仅验证不部署'
        type: string
        required: false
        default: "false"

AtomGit Action 的 workflow_dispatch.inputs 仅支持 string 类型参数。所有输入值均为字符串，如需数字或布尔语义，可在工作流中通过表达式进行类型转换。

workflow_call 可重用工作流触发​

workflow_call 用于定义可被其他 workflow 调用的可重用工作流：

on:
  workflow_call:
    inputs:
      config_path:
        description: "配置文件路径"
        type: string
        required: false
        default: "config/default.json"
    secrets:
      deploy_token:
        description: "部署 token"
        required: true

基于性能考量，workflow_call 目前仅支持 1 层嵌套调用，即可重用工作流不能再调用另一个可重用工作流。

schedule 定时触发​

schedule 使用 POSIX cron 语法：

on:
  schedule:
    - cron: "0 2 * * *"

注意：

  • cron 使用 UTC 时区。
  • 定时任务可能存在数分钟的调度延迟。
  • schedule 仅在仓库的默认分支生效。
  • cron 的五段式含义：分钟 小时 日 月 星期。

多事件组合​

同一 workflow 可同时响应多个事件：

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:
  schedule:
    - cron: "0 2 * * *"

branches / branches-ignore 过滤​

  • branches：白名单模式，仅匹配的分支触发。
  • branches-ignore：黑名单模式，不匹配的分支触发。
  • 两者不能同时使用。
on:
  push:
    branches:
      - main
      - develop
      - 'feature/**'
on:
  push:
    branches-ignore:
      - experimental

paths / paths-ignore 过滤​

  • paths：仅当匹配的路径发生变更时触发。
  • paths-ignore：仅当不匹配的路径发生变更时触发。
  • 两者不能同时使用。
  • paths 匹配前 300 个变更文件，超出部分不参与匹配判断。
on:
  push:
    branches:
      - main
    paths:
      - "src/**"
      - "package.json"
      - "!src/docs/**"
on:
  push:
    branches:
      - main
    paths-ignore:
      - "docs/**"
      - "**.md"

tags / tags-ignore 过滤​

on:
  push:
    tags:
      - "v*"
      - "release-*"
on:
  push:
    tags-ignore:
      - "v*-alpha"

否定模式（!）​

在 branches、paths、tags 中可以使用 ! 前缀表示否定匹配：

on:
  push:
    branches:
      - "feature/**"
      - "!feature/experimental"
    paths:
      - "src/**"
      - "!src/docs/**"

注意：否定模式必须与肯定模式组合使用。如果仅有否定模式（如 branches: ["!main"]），workflow 将不会触发。