Gitee Support Center / detail

    流水线

    1、基本信息

    • 流水线名称:流水线的名字,同一代码库内可以重复,但不建议设定重复的名字
    • 流水线唯一标识:流水线的唯一标识,同一代码库内不可重复

    使用事例:
    【推荐】您可以在可视化编辑界面定义:
    配置基本信息

    您可以在Yml中直接定义:

    # 当前yml文件版本,默认 1.0
    version: '1.0'
    # 流水线标识,支持数字、字母(小写)、中划线、下划线,仓库内唯一
    name: pipeline-demo 
    # 流水线名称,支持中文、数字、字母、通用符号等,最大128个字符
    displayName: 流水线Demo     

    2、触发事件

    触发事件是流水线能够执行的“触发器”,分为Push触发、Pull Request触发、定时触发三类。

    2.1、Push触发

    • Push事件由以下三种行为产生,本地推送、分支合并、PR合并。因此,只要在流水线中配置了Push事件触发,以上三种操作都会自动触发流水线执行。
    • 在Push事件下,提供以下三种匹配规则,三种匹配规则是交集关系,即同时设置了匹配规则,只有满足所有规则时才可触发流水线
      • 分支匹配:共有以下四种匹配规则
        • 前缀匹配:如填写dev,则匹配dev开头的所有分支;当填写空时,匹配所有分支
        • 精确匹配:如填写dev,仅会匹配dev分支
        • 正则匹配:如填写dev.*,则匹配前缀为dev的所有分支
        • 精确排除:如填写dev,则向dev分支提交代码不会触发流水线。精确排除的规则优先级最高,通常和其他规则混合使用
      • Tag匹配:同分支匹配一样,共有以下四种匹配规则
        • 前缀匹配:如填写v1,则匹配v1开头的所有Tag;当填写空时,匹配所有Tag
        • 精确匹配:如填写v1.1.1,仅会匹配v1.1.1 Tag
        • 正则匹配:如填写v1.*,则匹配前缀为v1的所有Tag
        • 精确排除:如填写v1.1.1,则创建v1.1.1 Tag不会触发流水线。精确排除的规则优先级最高,通常和其他规则混合使用
      • 提交注释关键字匹配:仅支持正则匹配
        • 正则匹配:如填写.*build.*,则在提交代码时Commit Message中包含build关键字的都可以触发流水线

    具体场景:
    分支匹配配置了精确匹配master,Tag匹配配置了前缀匹配v1,提交注释关键字匹配配置了.*build.*,如下图
    Push具体场景
    那么:

    • 当向master提交代码,但Commit Message是 “Gitee Go”时,流水线不能触发
    • 当向master提交代码,但Commit Message是 “Gitee build Go”时,流水线能触发
    • 当推送Tag为v1.10.1,但Commit Message是 “Gitee Go”时,流水线不能触发
    • 当推送Tag为v1.10.1,但Commit Message是 “Gitee build Go”时,流水线能触发

    使用事例:
    【推荐】您可以在可视化编辑界面定义:
    Push配置

    您可以在Yml中直接定义:

    # 表示开启流水线自动触发
    triggers:
      # 开启push事件监听,可匹配分支、Tag、提交注释(Commit Message)
      push:
        # 开启分支匹配,支持数字、字母(包含大小写)、中划线、下划线以及通用字符,最大64个字符
        branches: 
          # 开启前缀匹配,可以填写多个前缀,不填默认监听所有分支
          prefix:
            - release
          # 开启精确匹配,可以填写多个分支,请填写完整分支名称
          precise:
            - master
          # 开启正则匹配,可以填写多个正则表达式,请填写正则表达式
          include:
            - master
            - dev*
          # 开启精确排除,可以填写多个分支,请填写完整分支名称
          exclude:
            - release
        # 开启Tag匹配,支持数字、字母(包含大小写)、中划线、下划线以及通用字符,最大64个字符
        tags:
          # 开启前缀匹配,可以填写多个前缀,不填默认监听所有Tag
          prefix:
            - v1
          # 开启精确匹配,可以填写多个Tag,请填写完整Tag名称
          precise:
            - v1.1.1
          # 开启正则匹配,可以填写多个正则表达式,请填写正则表达式
          include:
            - ^v1.*
          # 开启精确排除,可以填写多个Tag,请填写完整Tag名称
          exclude:
            - v3
        # 开启提交注释监听,支持中文、数字、字母(包含大小写)、中划线、下划线以及通用字符,最大256个字符
        commitMessages:
          # 开启正则匹配,可以填写多个正则表达式,请填写正则表达式
          include:
            - '.*部署测试'

    2.2、Pull Request触发

    • Pull Request事件由页面发起PR、更新PR行为产生。因此,只要在流水线中配置了Push事件触发,以上两种种操作都会自动触发流水线执行。
    • 在Push事件下,提供以下三种匹配规则,三种匹配规则是交集关系,即同时设置了匹配规则,只有满足所有规则时才可触发流水线
      • 分支匹配:共有以下四种匹配规则

        • 前缀匹配:如填写dev,则匹配dev开头的所有分支;当填写空时,匹配所有分支
        • 精确匹配:如填写dev,仅会匹配dev分支
        • 正则匹配:如填写dev.*,则匹配前缀为dev的所有分支
        • 精确排除:如填写dev,则向dev分支提交代码不会触发流水线。精确排除的规则优先级最高,通常和其他规则混合使用
      • 提交注释关键字匹配:仅支持正则匹配,此处匹配的是发起PR时的标题,如下图

        • 正则匹配:如填写.*build.*,则在提交代码时Commit Message中包含build关键字的都可以触发流水线
          PR标题匹配
      • 评论匹配:仅支持正则匹配,此处匹配的PR已经发起后,对PR进行评论,如下图

        • 正则匹配:如填写.build.,则在提交代码时Commit Message中包含build关键字的都可以触发流水线
          PR评论匹配

    重要:PR触发构建时执行逻辑说明!!!
    当发起一个PR时,就会存在源分支、目标分支两个主体。以下内容以dev分支向master分支发起一个PR为例说明所有情况。此时dev为源分支,master为目标分支。

    • 创建PR ,发起dev向master的PR,根据dev下最新commit的yml触发流水线,流水线的构建任务拉取代码时会进行自动预合并,即构建的代码为 master + dev的增量代码
    • PR创建后 ,master有代码更新,不会引起本次PR变化
    • PR创建后 ,向dev提交补丁,会触发PR更新,此时的逻辑和PR创建时一样。仍然读取源分支dev下最新的commit下的yml并生成流水线
    • PR创建后 ,向PR评论,会触发PR的更新,此时的逻辑和PR创建时一样。仍然读取源分支dev下最新的commit下的yml并生成流水线
    • PR合并后 ,会产生一条Push消息,不会引起本次PR变化

    使用事例:
    【推荐】您可以在可视化编辑界面定义:
    PR编辑

    您可以在Yml中直接定义:

    # 表示开启流水线自动触发
    triggers:
      # 开启pull request事件监听,可匹配分支、提交注释(PR Title)、评论
      pr:
        # 开启分支匹配,支持数字、字母(包含大小写)、中划线、下划线以及通用字符,最大64个字符
        branches: 
          # 开启前缀匹配,可以填写多个前缀,不填默认监听所有分支
          prefix:
            - release
          # 开启精确匹配,可以填写多个分支,请填写完整分支名称
          precise:
            - master
          # 开启正则匹配,可以填写多个正则表达式,请填写正则表达式
          include:
            - master
            - dev*
          # 开启精确排除,可以填写多个分支,请填写完整分支名称
          exclude:
            - release
        # 开启提交注释监听,支持中文、数字、字母(包含大小写)、中划线、下划线以及通用字符,最大256个字符
        commitMessages:
          # 开启正则匹配,可以填写多个正则表达式,请填写正则表达式
          include:
            - '.*部署测试'
        # 开启PR评论监听,支持中文、数字、字母(包含大小写)、中划线、下划线以及通用字符,最大256个字符
        comments:
          # 开启正则匹配,可以填写多个正则表达式,请填写正则表达式
          include:
            - '.*部署测试'

    2.3、定时触发

    定时触发根据标准的cron表达式填写,秒级系统默认填充。
    基本规则

    cron文件的格式:M H D m d y 
    M: 分钟(0-59)
    H:小时(0-23)
    D:天(1-31)
    m: 月(1-12)
    d: 一星期内的天(1~7)注:根据国外时间来,周日是1
    y:年,可以选填
    
    除数字外,还有几个特殊符号"*"、"/"和"-"、","
    *:代表所有取值范围内数字
    /:代表每的意思
    */5:表示每5个单位
    -:代表从某个数字到某个数字,
    ,:分开几个离散的数字。
    
    0 */2 * * ?   每两小时进行一次
    0 23-7/2,8 * * ?  晚上11点到7点每两小时一次,8点一次
    15 10 ? * 1-5 周日至周四的上午10:15触发
    0 12 ? * 4 表示每个星期三中午12点
    
    注意:星期和天不能同时用*,否则会发生冲突,此外输入要用英文输入法

    使用事例:
    【推荐】您可以在可视化编辑界面定义:
    定时触发

    您可以在Yml中直接定义:

    # 表示开启流水线自动触发
    triggers:
      schedule:
          # 目前仅支持填写一个定时表达式,暂时还未开放多个
        - cron: '0 */2 * * ?'

    3、任务编排

    3.1、阶段设置

    阶段是流水线中的二级元素,一个阶段通常是具有一些列相似性任务的集合,如“代码扫描”阶段,他可以有“代码规范扫描”、“代码安全扫描”、“代码缺陷扫描”三个任务。一条流水线可以有多个阶段,按照顺序串行执行。阶段有以下基本元素:

    • 阶段名称:阶段的名字,同一条流水线内可以重复
    • 阶段标识:阶段的唯一标识,同一条流水线内不可重复
    • 触发方式
      • 自动触发:上游阶段构建成功之后,自动触发下游阶段,如果失败,则不允许触发下游
      • 手动触发:上游阶段构建成功之后,不会自动触发下游阶段,需要手动点击执行按钮
    • 失败策略
      • 快速失败 :主要应用并发任务执行时的场景,如下图所示。在构建阶段有三个并行任务链,当编译阶段开始执行时,三个任务链会同时开始执行。其中Step1-1执行失败后,即使Step2-1、Step3-1执行成功,也不会触发下游任务执行。即当选择“快速失败”时,并行的任务链条是可以互相影响执行状态的。
        快速失败和自然失败
      • 自然失败 :与快速失败相反,当选择“自然失败”时,并行的任务链条互不影响,即使Step1-1执行失败,它只会影响Step1-2、Step1-3不能继续执行,而Step2、Step3链条仍会正常向下执行,直到链条全部执行完毕

    使用事例
    推荐】您可以在可视化编辑界面定义:
    新建阶段
    编辑阶段

    您可以在Yml中直接定义:

    # 配置阶段,必填字段。可以配置多个stage,按照配置顺序串行执行
    stages:
      - stage:        
        # 阶段标识,支持数字、字母(小写)、中划线、下划线,当前流水线内唯一
        name: compile
        # 阶段名称,支持中文、数字、字母、通用符号等,最大128个字符
        displayName: 编译   
        # 阶段触发策略,naturally表示自然失败,fast表示快速失败
        strategy: naturally     
        # 阶段触发方式,auto表示自动触发,manual表示手动触发
        trigger: auto

    3.2、任务设置

    任务是流水线的三级元素,属于阶段的子元素,是最小执行单元。在阶段可以定义任务按照串行或并行两种顺序执行,任务默认全部是自动执行,不支持手动执行。一个任务对应一个插件,任务是插件的执行容器。基于此,流水线的整体模型为: 一个流水线对应多个阶段,一个阶段对应多个任务,一个任务对应一个插件

    一个任务包含以下基本信息:

    • 任务名称:任务的名字,同一阶段内可以重复
    • 任务标识:任务的唯一标识,同一阶段内不可重复

    使用事例:
    【推荐】您可以在可视化编辑界面定义:
    新建任务
    配置任务
    新建串、并行任务

    您可以在Yml中直接定义:

    # 配置任务,必填字段。可以配置多个任务,并定义串并行
    steps:
        # 当前任务所对应的插件标识,您可以通过 点击此处>>> 寻找对应的插件
      - step: build@maven 
        # 任务标识,支持数字、字母(小写)、中划线、下划线,当前阶段内唯一
        name: build_maven_1
        # 任务名称,支持中文、数字、字母、通用符号等,最大128个字符
        displayName: Maven 构建-1
      - step: build@maven
        name: build_maven_2
        displayName: Maven 构建-2
        # 依赖配置,表示 Maven 构建-2 这个任务 和 Maven 构建-1 串行执行,每个任务的出度和入肚均为1
        dependsOn: build_maven_1
      - step: build@maven
        name: build_maven_3
        displayName: Maven 构建-3

    4、参数设置

    4.1、系统级参数

    系统级参数是Gitee Go内置参数,只要产生一条构建记录即可产生以下参数,并可以在任何任务内使用。全部使用GITEE_xxx形式描述,使用${GITEE_xxx}$GITEE_xxx可以引用参数。系统参数全部由系统生成,不可变更。

    参数 描述
    GITEE_PIPELINE_NAME 流水线唯一标识
    GITEE_PIPELINE_DISPLAY_NAME 流水线名字
    GITEE_PIPELINE_BUILD_NUMBER 流水线构建号
    GITEE_PIPELINE_TRIGGER_USER 流水线触发人
    GITEE_COMMIT_MESSAGE Push和Tag的message或PR的title
    GITEE_BRANCH Push下的分支或PR下的目标分支
    GITEE_COMMIT Push和Tag的commit或PR的目标分支commit
    GITEE_SOURCE_BRANCH 发起PR时的源分支
    GITEE_SOURCE_COMMIT 发起PR时的源分支commit
    GITEE_PULL_ID 发起PR时的PR号
    GITEE_REPO 代码仓库名
    GITEE_STAGE_NAME 阶段唯一标识
    GITEE_STAGE_DISPLAY_NAME 阶段名字
    GITEE_STAGE_STRATEGY 阶段触发策略,manual 或 auto

    使用事例:
    【推荐】您可以在可视化编辑界面引用:
    引用系统变量

    您可以在Yml中直接引用:

    # 如下在Maven构建中,可这样使用
    - step: build@maven
      name: build_maven_2
      displayName: Maven 构建-2
      jdkVersion: 8
      mavenVersion: 3.3.9
      commands:
        - echo ${GITEE_PIPELINE_NAME}

    4.2、流水线级参数

    流水线级参数属于用户自定义参数,可以在此条流水线内任何阶段、任务内使用。其中GITEE_GO_为系统保留字。流水线级参数为用户自定义参数,可以变更,您可以通过执行以下命令来更改参数或创建参数echo 'Key=Value' >> GITEE_PARAMS,其中GITEE_PARAMS为参数专用处理文件。
    使用事例:
    【推荐】您可以在可视化编辑界面中定义并引用:
    定义流水线级参数

    引用流水线级参数

    您可以在Yml中直接定义并引用:

    # 非必填字段
    variables:
      // Key:支持数字、字母(包含大小写)、中划线、下划线,不支持特殊字符,最大32个字符,其中GITEE_、GO_为系统保留字
      // Value:请支持数字、字母、通用符号、中文等,最大256个字符
      PIPELINE_A: aaa
      
     # 定义好之后可以在任务中引用,如下在Maven构建中引用
    - step: build@maven
      name: build_maven_2
      displayName: Maven 构建-2
      jdkVersion: 8
      mavenVersion: 3.3.9
      commands:
        - echo ${PIPELINE_A}
        # 更改参数值
        - echo '${PIPELINE_A}=bbb' >> GITEE_PARAMS
        # 通生成一个新参数
        - echo '${PIPELINE_C}=ccc' >> GITEE_PARAMS

    5、高级设置

    5.1、阻塞构建

    阻塞构建是为了解决资源较为稀缺、多人协作不会互相污染环境而设置的。阻塞构建共有两个选项,分别是不阻塞构建和上一次构建未结束时阻塞构建:

    • 不阻塞构建:正常的,默认的构建方式,允许同一条流水线下多个构建并行执行
    • 上一次构建未结束时阻塞构建:上一条流水线未结束的时候,下一条流水线不触发;当上一条流水线运行结束,下一条流水线才会自动触发。

    场景事例:

    一条流水线由 <编译、部署测试环境、功能测试> 三个阶段组成。在A同学的第一次提交触发的#1构建中,<编译-部署测试环境>两个阶段已经执行完毕,目前正在进行功能测试。此时B同学提交一次代码触发了#2构建,跑到 部署测试环境 阶段时,A同学在#1构建的功能测试被中断而失败。当不希望上述问题发生时,可以限定流水线构建的顺序执行。如果上一次构建没有全部执行完毕,下一次构建处于等待中状态。

    具体配置:
    【推荐】您可以在可视化编辑界面中定义:
    输入图片说明

    您可以在Yml中直接定义:

    # 非必填字段
    strategy:
      # true开启阻塞构建,false表示不开启,默认false
      blocking: false        

    Search