文档

流水线任务 jobs

更新时间:

流水线任务jobs:流水线任务 job 可以为多个步骤 steps 的组合(多个步骤共享工作空间,共同完成指定任务), 或一个组件 component 的调用(调用组件执行指定任务,组件任务支持重试、跳过等更多操作)。

示例

  • 以下为一个任务添加多个步骤的配置示例:

stages:
  build_stage:
    name: 构建阶段
    jobs:
      build_job: 
        name: 构建任务
        runsOn: public/cn-beijing
        steps:                                # steps 配置任务步骤
          build_step:                        
            step: JavaBuild                   
            name: java构建                     
            with:                            
              ......
          upload_step:
            step: ArtifactUpload
            name: 构建物上传
            with:
              ......
  • 以下为一个任务实现一个组件的配置示例:

stages:
  build_stage:
    name: 构建阶段
    jobs:
      deploy_job:
        name: 主机组部署任务
        component: VMDeploy                # component 配置任务组件
        with:                              
          artifact: $[stages.build_stage.build_job.upload_step.artifacts.default]
          ......

详细说明

stages.<stage_id>.jobs

流水线任务,流水线任务可以为多个步骤 steps 的组合, 或一个组件 component 的实现。

stages.<stage_id>.jobs.<job_id>

必填。流水线任务 id,唯一标识流水线任务。job_id 只能包含字母、数字和 _ ,且必须以字母开头。长度限制 30 个字符。

stages.<stage_id>.jobs.<job_id>.name

如不填写,则使用job_id的值。长度限制 30 个字符。流水线任务的展示名称。

stages.<stage_id>.jobs.<job_id>.runsOn

非必填,默认使用云效北京构建集群。 流水线任务运行的集群环境,可以使用云效提供的公共集群环境,也可以使用私有构建集群。

集群环境

YAML 标识

备注

云效北京构建集群

public/cn-beijing

云效提供北京公共集群,若不指明集群环境,默认使用

云效中国香港构建集群

public/cn-hongkong

云效提供中国香港公共集群

私有构建集群

private/私有构建集群ID

通过私有构建集群添加

如:

jobs:
  my_job:
    name: 我的任务
    runsOn: public/cn-beijing
stages.<stage_id>.jobs.<job_id>.needs

非必填,默认一个阶段内的所有任务并行执行。若任务间有依赖关系,可通过needs描述阶段内的任务依赖关系。注意:

  • needs支持跨阶段的任务之间相互依赖。

  • 请确保依赖后的任务之间,有明确的先后关系。切勿出现循环依赖情况,如: A 依赖 B,B 依赖 C,C 依赖 A。

填写依赖任务的 <job_id>,如:

jobs:
  test_job:
    name: 测试任务
  build_job:
    name: 构建任务
    needs: test_job
stages.<stage_id>.jobs.<job_id>.driven

非必填,默认为 auto 自动执行。通过driven设置任务的触发方式,目前支持两种方式:

  • auto:自动执行

  • manual:手动确认执行

如:

jobs:
  my_job:
    name: 我的任务
    runsOn: public/cn-beijing
    driven: manual		#手动确认执行任务
stages.<stage_id>.jobs.<job_id>.condition

非必填,默认只有前序依赖任务全部成功后才执行本任务。通过condition判断本任务是否满足条件,若满足条件执行本任务。通过填写函数表达式如:

jobs:
  my_job:
    name: 我的任务
    runsOn: public/cn-beijing
    condition: |
      "${CI_COMMIT_REF_NAME}" == "master"		# 运行分支为 master 时执行该任务

支持关系操作符、逻辑操作符:

操作符

说明

示例

==

等于

condition: "${CI_COMMIT_REF_NAME}" == "master"

!=

不等于

condition: "${CI_COMMIT_REF_NAME}" == "master"

&&

condition: "${CI_COMMIT_REF_NAME}" == "master" && succeed()

||

condition: "${CI_COMMIT_REF_NAME}" == "master" || "${CI_COMMIT_REF_NAME}" == "develop"

提供一组内置函数,可用于表达式:

函数

说明

示例

startsWith(searchString, searchValue)

如果 searchString 以 searchValue 开头,将返回 true

condition: startsWith('Hello world','He')

endsWith(searchString, searchValue)

如果 searchString 以 searchValue 结尾,将返回 true

condition: endsWith('Hello world','ld')

contains(search, item)

输入 search 是一个数组,item 是数组中的一个元素,此函数将返回 true

condition: contains('["aa", "bb", "cc"]', 'aa')

weekDay()

此函数将返回一周中的某一天(Monday、Tuesday、Wednesday、Thursday、Friday、Saturday、Sunday)

condition: weekDay()=="Thursday"

timeIn(startTime, endTime)

此函数判断当前时间是否在 startTime 和 endTime 之间

condition: timeIn("20:00:00", "22:00:00")

说明:函数参数可以填写存在的变量,例如设置了流水线变量 TEST_VAR=["aa", "bb", "cc"],可以在函数中用${}引用该变量:

jobs:
  job_1:
    name: 1
    condition: contains('${TEST_VAR}', 'aa')

可以通过任务状态函数,获取前序依赖任务的执行状态,函数入参为前序依赖任务的 <job_id>。

函数

说明

示例

always()

默认返回 true

condition: always()

succeed()

前序任务执行成功返回 true

condition: succeed('job_id_1','job_id_2')

failed()

前序任务执行失败返回 true

condition: failed('job_id_1','job_id_2')

注意:任务状态函数,若入参不填则为前序所有任务。如 succeed() 要求前序依赖任务全部成功才返回 true。 任务状态函数,入参必须为前序任务的 <job_id>。若填写了无依赖关系的 <job_id>,则无法正常执行。示例:

jobs:
  job_1:
    name: 任务1
  job_2:
    name: 任务2
  job_3:
    name: 任务3
    needs: 
      - job_1
      - job_2
    condition: succeed(job_1) || succeed(job_2) # job1 执行成功或 job2 执行成功,才执行job3
stages.<stage_id>.jobs.<job_id>.sourceOption

非必填,默认下载流水线中配置的所有流水线源文件。当流水线配置多个代码源时,可以任务节点是否下载源文件,或者下载指定源文件,通过填写<source_id>指定你要写的源文件。

使用场景

说明

示例

下载所有源文件

不填写sourceOption

不填写

不下载源文件

填写sourceOption,内容为空

sourceOption: []

下载指定源文件

填写sourceOption及<source_id>

sourceOption: [repo_1,repo_2]

stages.<stage_id>.jobs.<job_id>.steps

流水线任务可为多个步骤 steps 的组合,多个步骤共享工作空间,共同完成指定任务。

详细请查看“流水线步骤 steps”。

stages.<stage_id>.jobs.<job_id>.component

流水线任务可调用一个组件 component 执行指定任务,组件任务支持重试、跳过等更多操作。

详细请查看“流水线组件 component”。

stages.<stage_id>.jobs.<job_id>.with

当流水线任务为一个组件 component 调用时,通过with填写组件所需的执行参数。示例:

jobs:
  deploy_job:
  name: 主机组部署任务
  runsOn: public/cn-beijing
  component: VMDeploy             # 指定组件
  with:                           # 填写组件的参数
    artifact: $[stages.build_stage.build_job.upload_step.artifacts.default]
    machineGroup: <your-machine-group-id>
    ......

详细请查看“流水线组件 component”。

stages.<stage_id>.jobs.<job_id>.plugins

非必填。流水线任务消息通知可以通过配置 plugins 实现钉钉、邮件、企业微信、飞书、Webhook等渠道的消息通知。

详细请查看“任务插件 plugins”。