GitHub Actions 事件触发 #

事件触发是工作流启动的核心机制。本节详细介绍各种事件触发方式和过滤条件。

事件概述 #

什么是事件？ #

事件是触发工作流运行的特定活动。GitHub Actions支持多种事件类型：

代码相关事件（push、pull_request）
问题相关事件（issues、issue_comment）
发布相关事件（release、create）
定时事件（schedule）
手动事件（workflow_dispatch）
外部事件（repository_dispatch）

基本语法 #

yaml

on: push

# 或
on: [push, pull_request]

# 或带过滤条件
on:
  push:
    branches: [main]

push事件 #

基本用法 #

yaml

on: push

分支过滤 #

yaml

on:
  push:
    branches:
      - main
      - 'release/**'
      - '!release/**-alpha'  # 排除匹配的分支

标签过滤 #

yaml

on:
  push:
    tags:
      - 'v*'
      - 'v*.*.*'

路径过滤 #

yaml

on:
  push:
    paths:
      - 'src/**'
      - 'tests/**'
      - '.github/workflows/**'
    paths-ignore:
      - '**.md'
      - 'docs/**'

组合过滤 #

yaml

on:
  push:
    branches:
      - main
    paths:
      - 'src/**'

pull_request事件 #

基本用法 #

yaml

on: pull_request

分支过滤 #

yaml

on:
  pull_request:
    branches:
      - main
      - 'release/**'

活动类型 #

yaml

on:
  pull_request:
    types:
      - opened        # PR创建
      - synchronize   # PR同步（新提交）
      - reopened      # PR重新打开
      - closed        # PR关闭
      - labeled       # PR添加标签
      - unlabeled     # PR移除标签
      - review_requested    # 请求审查
      - review_request_removed  # 移除审查请求

路径过滤 #

yaml

on:
  pull_request:
    branches: [main]
    paths:
      - 'src/**'
    paths-ignore:
      - '**.md'

workflow_dispatch事件 #

基本手动触发 #

yaml

on: workflow_dispatch

带输入参数 #

yaml

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deploy environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production
      
      debug:
        description: 'Enable debug mode'
        required: false
        type: boolean
        default: false
      
      version:
        description: 'Version to deploy'
        required: true
        type: string
      
      config:
        description: 'Configuration'
        required: false
        type: environment

使用输入参数 #

yaml

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        run: |
          echo "Environment: ${{ github.event.inputs.environment }}"
          echo "Debug: ${{ github.event.inputs.debug }}"
          echo "Version: ${{ github.event.inputs.version }}"

schedule事件 #

基本定时触发 #

yaml

on:
  schedule:
    - cron: '0 0 * * *'  # 每天UTC 0点

Cron表达式 #

text

┌───────────── 分钟 (0 - 59)
│ ┌───────────── 小时 (0 - 23)
│ │ ┌───────────── 日 (1 - 31)
│ │ │ ┌───────────── 月 (1 - 12)
│ │ │ │ ┌───────────── 星期 (0 - 6) (0是周日)
│ │ │ │ │
* * * * *

常用Cron表达式 #

yaml

on:
  schedule:
    - cron: '0 0 * * *'      # 每天UTC 0点
    - cron: '0 0 * * 1'      # 每周一UTC 0点
    - cron: '0 0 1 * *'      # 每月1日UTC 0点
    - cron: '*/15 * * * *'   # 每15分钟
    - cron: '0 9 * * 1-5'    # 周一到周五UTC 9点

注意事项 #

定时任务运行在最接近的5分钟间隔
最小间隔为5分钟
时区为UTC

repository_dispatch事件 #

接收外部事件 #

yaml

on:
  repository_dispatch:
    types: [my-event]

触发事件 #

使用GitHub API触发：

bash

curl -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/owner/repo/dispatches \
  -d '{"event_type": "my-event", "client_payload": {"env": "production"}}'

使用payload #

yaml

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo "Event: ${{ github.event.action }}"
          echo "Environment: ${{ github.event.client_payload.env }}"

其他常用事件 #

issues事件 #

yaml

on:
  issues:
    types: [opened, closed, labeled]

issue_comment事件 #

yaml

on:
  issue_comment:
    types: [created]

release事件 #

yaml

on:
  release:
    types: [published, created, edited]

create事件 #

yaml

on:
  create:
    # 创建分支或标签时触发

delete事件 #

yaml

on:
  delete:
    # 删除分支或标签时触发

fork事件 #

yaml

on:
  fork:
    # 仓库被fork时触发

watch事件 #

yaml

on:
  watch:
    types: [started]
    # 用户star仓库时触发

workflow_call事件 #

yaml

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
    secrets:
      deploy-token:
        required: true

事件过滤详解 #

分支过滤 #

yaml

on:
  push:
    branches:
      - main                    # 精确匹配
      - 'release/**'            # glob模式匹配
      - '!release/**-alpha'     # 排除匹配

Glob模式支持：

模式	描述
`*`	匹配任意字符（不含/）
`**`	匹配任意字符（含/）
`?`	匹配单个字符
`[abc]`	匹配字符集
`[!abc]`	排除字符集

路径过滤 #

yaml

on:
  push:
    paths:
      - 'src/**'                # 匹配src目录下所有文件
      - '**.js'                 # 匹配所有js文件
      - '!**.test.js'           # 排除测试文件
    paths-ignore:
      - 'docs/**'               # 忽略docs目录
      - '**.md'                 # 忽略markdown文件

类型过滤 #

yaml

on:
  pull_request:
    types:
      - opened
      - synchronize
      - reopened

多事件组合 #

并行触发 #

yaml

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

条件判断事件类型 #

yaml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check event
        run: |
          if [ "${{ github.event_name }}" == "push" ]; then
            echo "Push event"
          elif [ "${{ github.event_name }}" == "pull_request" ]; then
            echo "Pull request event"
          fi

事件上下文 #

github上下文 #

yaml

jobs:
  info:
    runs-on: ubuntu-latest
    steps:
      - name: Event info
        run: |
          echo "Event name: ${{ github.event_name }}"
          echo "Event action: ${{ github.event.action }}"
          echo "Repository: ${{ github.repository }}"
          echo "Branch: ${{ github.ref }}"
          echo "SHA: ${{ github.sha }}"
          echo "Actor: ${{ github.actor }}"

常用事件属性 #

yaml

# push事件
${{ github.event.after }}           # 推送后的SHA
${{ github.event.before }}          # 推送前的SHA
${{ github.event.created }}         # 是否是新分支
${{ github.event.deleted }}         # 是否删除分支

# pull_request事件
${{ github.event.pull_request.number }}    # PR编号
${{ github.event.pull_request.title }}     # PR标题
${{ github.event.pull_request.head.ref }}  # PR源分支
${{ github.event.pull_request.base.ref }}  # PR目标分支

# workflow_dispatch事件
${{ github.event.inputs.environment }}     # 输入参数

完整示例 #

CI工作流 #

yaml

name: CI

on:
  push:
    branches: [main, develop]
    paths-ignore:
      - '**.md'
      - 'docs/**'
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

部署工作流 #

yaml

name: Deploy

on:
  push:
    tags:
      - 'v*'
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment'
        required: true
        type: choice
        options:
          - staging
          - production
        default: 'staging'

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ github.event.inputs.environment || 'production' }}
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: |
          echo "Deploying to ${{ github.event.inputs.environment || 'production' }}"
          echo "Version: ${GITHUB_REF#refs/tags/}"

定时任务 #

yaml

name: Scheduled Tasks

on:
  schedule:
    - cron: '0 0 * * *'      # 每天运行
  workflow_dispatch:

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Cleanup old artifacts
        run: echo "Cleaning up..."

最佳实践 #

1. 使用路径过滤减少不必要的运行 #

yaml

on:
  push:
    paths:
      - 'src/**'
      - 'tests/**'
    paths-ignore:
      - '**.md'

2. 使用并发控制 #

yaml

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

3. 使用手动触发进行生产部署 #

yaml

on:
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options:
          - staging
          - production

4. 组合多种触发方式 #

yaml

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

下一步学习 #

定时触发 - 深入学习定时任务
手动触发 - 学习手动触发配置
上下文与表达式 - 使用上下文信息

小结 #

事件是触发工作流的核心机制
支持多种事件类型和过滤条件
使用分支、路径、类型过滤精确控制触发
workflow_dispatch支持手动触发和输入参数
schedule支持定时触发
repository_dispatch支持外部触发
使用并发控制优化资源使用