# 流水线触发方式on
使用on关键字可指定流水线的自动触发方式。可以在on中指定多个代码事件触发流水线的方式，支持通过过滤规则实现仅当满足特定的分支、文件、标签变更时才触发流水线；也可以在on中指定定时任务执行流水线。
#### on.\<event_name\>.types
指定触发流水线的代码事件的具体类型，当前仅支持对合并请求事件进行类型过滤：
表1合并请求事件类型 
| **合并请求事件类型** | **说明**     |
|:---|:---|
| opened       | 合并请求被创建。   |
| synchronize  | 源分支被更新。    |
| closed       | 合并请求被合入。   |
| reopened     | 合并请求被重新打开。 |
   
默认情况下，流水线会在合并请求发生opened、synchronize、reopened事件时触发，以下示例表示仅当合并请求被合入时才触发流水线：
```
on:
  pull_request:
    types:
      - closed
```
#### on.\<pull_request\>.\<branches\|branches-ignore\>
使用pull_request事件定义流水线针对特定分支的合并请求运行。**为避免产生歧义，不能在pull_request事件中同时指定branches和branches-ignore。**
- branches：指定在触发规则中包含某些分支或同时包含和排除某些分支，使用branches进行过滤。
- branches-ignore：指定在触发规则中排除某些分支时，使用branches-ignore进行过滤。
branches和branches-ignore支持以Glob模式进行匹配，具体匹配规则如下：
表2匹配规则 
| **匹配符** | **说明**                             | **示例**                                                                                                                                                                                                                                            |
|:---|:---|:---|
| \*      | 匹配0到多个任意字符（除"/"外）。                 | dev\*：可匹配dev、develop等，但无法匹配dev/test。                                                                                                                                                                                                              |
| ?       | 匹配任意一个字符。                          | dev?：可匹配dev1、dev2等，但无法匹配dev12。                                                                                                                                                                                                                    |
| \*\*    | 匹配0到多个任意字符。                        | dev\*\*：可匹配dev、develop、dev/test等。                                                                                                                                                                                                                 |
| \[\]    | 匹配括号内指定范围内的一个字符，范围限定在a-z、A-Z、0-9中。 | - v\[a-z\].\[0-9\]\*：可匹配va.1、vb.111等。  - v\[01\]：可匹配v0、v1。   |
| {}      | 匹配括号内的多个字符串。                       | {branch1,branch2}：可以匹配branch1、branch2。                                                                                                                                                                                                            |
| !       | 在字符串第一位定义，表示匹配除了后续字符串之外的任意字符串。     | !develop：表示匹配develop之外的所有字符串。                                                                                                                                                                                                                     |
   
**示例**
- **定义包含分支**
  ```
  on:
    pull_request:
      branches:
        - master
        - 'release**'
  ```
  如上定义表示流水线仅在合并请求事件的目标分支满足以下条件之一时运行：
  - 分支为master。
  
  - 分支名以release开头，如：release、release-1.0.0、release/1.0.0。
   
- **定义排除分支**
  ```
  on:
    pull_request:
      branches-ignore:
        - test
        - 'dev**'
  ```
  如上定义表示流水线会在任意分支的合并请求事件触发时运行，除非目标分支满足以下条件之一：
  - 分支为test。
  
  - 分支名以dev开头，如dev、develop-1.0.0、develop/1.0.0。
   
- **同时定义包含和排除分支**
  如果需要同时定义包含和排除分支，需在包含分支中定义"!"以排除特定的分支。
  ```
  on:
    pull_request:
      branches:
        - 'release**'
        - '!release/v1**'
  ```
  如上定义表示流水线仅在合并请求的目标分支满足以下全部条件时运行：
  - 分支名以release开头，如：release、release-1.0.0、release/1.0.0。
  
  - 分支名不以release/v1/\*\*开头，如：release/v1、release/v1.0、release/v1/1.0。
   
 
#### on.\<push\>.\<branches\|branches-ignore\|tags\|tags-ignore\>
使用push事件定义流水线针对特定分支/tag的代码提交运行。**为避免产生歧义，不能在push事件中同时指定branches、branches-ignore、tags和tags-ignore。**
- branches：指定在触发规则中包含某些分支或同时包含和排除某些分支时，使用branches进行过滤。
- branches-ignore：指定在触发规则中排除某些分支时，使用branches-ignore进行过滤。
- tags：指定在触发规则中包含某些tag或同时包含和排除某些tag时，使用tags进行过滤。
- tags-ignore：指定在触发规则中排除某些tag时，使用tags-ignore进行过滤。
**示例**
- **定义包含分支/tag**
  ```
  on:
    push:
      branches:
        - master
        - 'release**'
      tags:
        - v1
        - 'v2.*'
  ```
  如上定义表示流水线仅在代码提交的分支/tag满足以下条件之一时运行：
  - 分支为master。
  
  - 分支名以release开头，如：release、release-1.0.0、release/1.0.0。
  
  - tag为v1。
  
  - tag以v2.开头，如：v2.1、v2.1.1。
   
- **定义排除分支/tag**
  ```
  on:
    push:
      branches-ignore:
        - test
        - 'dev**'
      tags-ignore:
        - v1
        - 'v2.*'
  ```
  如上定义表示流水线会在任意代码提交事件时运行，除非分支/tag满足以下条件之一：
  - 分支为test。
  
  - 分支名以dev开头，如：dev、develop-1.0.0、develop/1.0.0。
  
  - tag为v1。
  
  - tag以v2.开头，如：v2.1、v2.1.1。
   
- **同时定义包含和排除分支/tag**
  如果需要同时定义包含和排除分支/tag，需在包含分支/tag中定义"!"以排除特定的分支/tag。
  ```
  on:
    push:
      branches:
        - 'release**'
        - '!release/v1**'
      tags:
        - 'v1**'
        - '!v1.1'
  ```
  如上定义表示流水线仅在代码提交的分支/tag满足以下所有情况时运行：
  - 分支名以release开头，如：release、release-1.0.0、release/1.0.0。
  
  - 分支名不以release/v1/\*\*开头，如：release/v1、release/v1.0、release/v1/1.0。
  
  - tag名以v1开头，如：v1、v1.2。
  
  - tag名不为v1.1。
   
 
#### on.\<push\|pull_request\>.\<paths\|paths-ignore\>
使用push和pull_request事件定义流水线在指定文件发生变更时运行。**为避免产生歧义，不能在push和pull_request事件中同时指定paths和paths-ignore。**
- paths：指定在触发规则中包含某些文件或同时包含和排除某些文件时，使用paths进行过滤。
- paths-ignore：指定在触发规则中排除某些文件时，使用paths-ignore进行过滤。
**示例**
- **定义包含文件**
  ```
  on:
    push:
      paths:
        - '**.java'
  ```
  表示流水线在代码提交变更的文件中至少有一个.java文件时运行。
  
- **定义排除文件**
  ```
  on:
    push:
      paths-ignore:
        - 'docs/**'
  ```
  表示流水线会在任意代码提交事件时运行，除非变更的文件列表全部在docs目录下。
  
- **同时定义包含和排除文件**
  如果需要同时定义包含和排除文件，需在包含文件中定义"!"以排除特定的文件。
  ```
  on:
    push:
      paths:
        - 'src/**'
        - '!src/docs/**'
  ```
  如上定义表示流水线仅在代码提交的变更文件列表中包含src目录下的文件，但不全是src/docs目录下的文件时运行。
  
 
#### on.schedule
使用on.schedule通过定义cron表达式使流水线在指定的UTC时间执行。以最后一次保存流水线时YAML内容中的定时任务配置为准，如果需要更新定时触发信息，需重新在页面上编辑YAML内容并保存流水线。定时任务执行时，会使用流水线源的默认分支。
```
on:
  schedule:
    - cron:  '0 0 12 * * ?'
    - cron:  '0 0 20 * * ?'
```
如上定义表示流水线有两个定时触发任务，分别在UTC时间每天12:00以及20:00触发。