流水线任务编排

YAML文件示例

stages:                                            #流水线阶段务
  test2:                                           #阶段的唯一标识
    name: 阶段_1                                   #阶段的名称
    select: always                                 #阶段是否总是运行
    jobs:                                          #流水线任务
      job_1:                                       #任务的唯一标识
        name: 任务名称                             #任务名称
        if: ${{ default() }}                       #流水线阶段任务执行时需要满足的前提条件，默认值为${{ default() }}
        runs-on: default
        select: selected_by_default                #任务选择的执行方式，默认为selected_by_default
        needs: [ ]                                 #依赖任务的唯一标识，依赖的任务需存在
        steps:                                     #定义组成任务的步骤
          - name: step1                            #步骤的名称
            uses: official_devcloud_cloudBuild     #插件信息，格式为插件名@插件版本。
            env:                                   #插件中的环境变量
              test: test                           
              test2: test2
            with:                                  #插件中输入的参数
              key1: value1                         
              key2: value2
      job_2:                       
        name: 任务名称2              
        if: ${{ default() }} }
        runs-on: [ self-hosted, test2 ]            #流水线任务支持的运行环境
        select: selected_by_default 
        needs: [ job_1 ] 
      job_3: 
        name: 任务名称2  
        if: ${{ default() }} 
        runs-on: [ dedicated, arm_linux ]
        select: selected_by_default 
        needs: [ job_2 ]             
    pre: 
      type: auto                                   #阶段的准入类型
    post:                                          #配置阶段的准出任务
      - name: step1 
        type: gate 
        with: 
          name: 创建策略-20250331212921
          level: tenant
      - name: step1 
        type: gate 
        with:                      
          name: xxw-chqtest-test
          level: project
post:                                             #后处理阶段的唯一标识
  name: 阶段名称                                  #后处理阶段的名称
  select: always                                  #后处理阶段是否总是运行，默认值为always
  jobs: 
    job1: 
      name: 任务名称 
      if: ${{ default() }} 
      select: selected_by_default 
      needs: [ ]                  
      steps: 
        - name: step1 
          uses: official_devcloud_cloudBuild 
          env: 
            test: test 
            test2: test2
          with: 
            key1: value1 
            key2: value2

编排流水线阶段

YAML流水线包含两种阶段：常规阶段和后置阶段。

• 常规阶段：编排常规阶段时，从编排的顶层结构，由一个stages键开始，stages下最多包含16个阶段

  stages:
    test2:
      name: 阶段_1
      select: selected_by_default
      jobs:    
      pre:
      - type: time_window
        with:
          timeZone: Pacific SA Standard Time
          timeRanges: "[[\"00:00\",\"00:00\"]]"
      post:             # 阶段的准出任务，可以配置多个

  表1 阶段的参数解释

  参数名	说明
  test2	阶段的唯一标识，仅支持大小写英文字母、数字、中划线或下划线，长度为1-128子字符串。
  name	流水线阶段名称。
  select	阶段是否总是运行。默认值为selected_by_default。 always：阶段总是运行。 selected_by_default：阶段默认运行，但不总是运行。
  jobs	流水线任务，每个阶段下最多配置100个任务。
  type	阶段的准入类型，当前支持三种准入类型。 auto：自动准入。 manual：手动准入。 time_window：时间窗准入，需配置时区和时间段。 timezone：指定时区。 ranges：指定时间段范围。
  post	配置阶段的准出任务，目前仅支持门禁插件。配置时需指定策略，支持租户策略和项目策略。 若使用租户策略，则需配置level：tenant；若使用项目策略，则需配置level：project。

• 后处理阶段：编排后处理阶段时，从编排的顶层结构下的post中配置。参数解释请参见表1。

  post:                  # 后处理阶段
    name: 阶段名称
    select: selected_by_default
    jobs:   
    pre:
    - type: auto
    post:             # 阶段的准出任务，可以配置多个

  表2 阶段的参数解释

  参数名	说明
  name	流水线后处理阶段名称。仅支持输入中文、大小写英文字母、数字、中划线、下划线、英文逗号、英文分号、英文冒号、英文句号、顿号、斜杠、英文括号、中文括号及空格，其中空格不可在名称开头或结尾使用，长度为1-128个字符。
  select	阶段是否总是运行。默认值为selected_by_default。 always：阶段总是运行。 selected_by_default：阶段默认运行，但不总是运行。
  jobs	流水线任务，每个阶段下最多配置100个任务。
  type	阶段的准入类型，当前支持三种准入类型。 auto：自动准入。 manual：手动准入。 time_window：时间窗准入，需配置时区和时间段。 timezone：指定时区。 ranges：指定时间段范围。
  post	配置阶段的准出任务，目前仅支持门禁插件。配置时需指定策略，支持租户策略和项目策略。 若使用租户策略，则需额外配置level：domain。

配置流水线任务

    jobs:                            
      job_1:                         
        name: 任务名称               
        if: ${{ default() }}         
        runs-on: default
        select: selected_by_default  
        needs: [ ]                   
        steps:                       
          - name: step1              
            uses: official_devcloud_cloudBuild     
            env:                     
              test: test             
              test2: test2
            with:                    
              key1: value1           
              key2: value2

配置流水线步骤

        steps:                       
          - name: step1              
            uses: official_devcloud_cloudBuild     
            env:                     
              test: test             
              test2: test2
            with:                    
              key1: value1           
              key2: value2

流水线任务jobs

• jobs.<job_id>.runs-on

  使用jobs.<job_id>.runs-on定义任务运行的资源池，支持三种类型：默认资源池（codearts-hosted）、自定义资源池（self-hosted）、专属资源池（dedicated-hosted）。如果需要进一步在资源池节点上自定义容器运行时，可配合container字段使用。

  1. 默认资源池

     默认资源池为codearts官方提供的资源类型，您可以通过以下方式快速定义。

     1. 通过官方默认标签定义。可以通过简写default使用默认资源池。

        jobs:
          job_name:
            runs-on: default 

     2. 选择指定类型标签定义。默认资源池建议使用三段式格式定义：[{os}-{arch}-{flavor}]。参数解释请参见表5。

        表5 参数解释

        字段	类型	必填	描述
        os	String	是	由两段组成 {os}-{version}。version代表os所支持的版本，具体信息可参见表6。
        arch	String	是	架构类型。 支持选择“x64”或“arm64”。
        flavor	String	是	机器规格。详细规格信息请参见表7。

        CodeArts默认资源池规格

        对于公共仓库，使用表6所示工作流标签的任务将按照相应的规范运行。

        当前默认资源池os支持的版本列表如下。支持的系统规格如表7。

        表6 os支持的版本列表

        OS	支持版本
        ubuntu	latest
        euler	latest

        表7 系统规格定义

        系统(OS)	规格	处理器（CPU）	内存（RAM）	存储
        ubuntu/euler	slim	1	4GB	GB
        ubuntu/euler	small	2	8GB	GB
        ubuntu/euler	medium	4	16GB	GB
        ubuntu/euler	large	8	32GB	GB
        ubuntu/euler	xlarge	16	64GB	GB

        jobs:
          job_name:
            runs-on: [euler-latest,x64,small]
            steps:
             - run: echo Hello world!

        数组中可以混合使用字符串和变量，例如：

        jobs:
          job_name:
            runs-on: ["${{ inputs.chosen-os }}","${{ inputs.arch }}",small]
            steps:
            - run: echo Hello world!

        

        使用变量必须使用""包裹，直接定义字符串不需要使用""包裹。

  2. 自定义资源池（self-hosted）
     自定义资源池通过group和labels对已定义的执行资源进行过滤。使用三段式格式定义：[{type}-{group}-{label1}-{lable2}....]。

     jobs:
       job_name:
         runs-on: [self-hosted,my-private-pool,x86,region=cn-north-4

     表8 参数解释

     字段	类型	必填	描述
     type	String	是	定义资源池的类型。 self-hosted：自定义资源池。 dedicated-hosted：专属资源池。 示例：self-hosted。
     group	String	是	资源池名称。系统根据此名称自动路由到对应的资源池。 示例：my-private-pool。
     labels	多个String	否	环境标签过滤器。 用于在指定资源池内进一步筛选具备特定属性的节点。支持配置一个或多个标签。 示例： 1. 简单标签（label1）：["x86"] 。 2. 键值对标签（label2）：["region=cn-north-4"]。

  3. 专属资源池（dedicated-hosted）

     定义同自定义资源池，通过group和labels对已定义的执行资源进行过滤。使用三段式格式定义：[{type}-{group}-{label1}-{lable2}....]。

     jobs:
       job_name:
         runs-on: [dedicated-hosted,my-dedicated-pool,x86,region=cn-north-4]

     表9 参数解释

     字段	类型	必填	描述
     type	String	是	定义资源池的类型。 self-hosted：自定义资源池。 dedicated-hosted：专属资源池。 示例：dedicated-hosted
     group	String	是	资源池名称。系统根据此名称自动路由到对应的资源池。 示例：my-dedicated-pool。
     labels	多个String	否	环境标签过滤器。 用于在指定资源池内进一步筛选具备特定属性的节点。支持配置一个或多个标签。 示例： 1. 简单标签（label1）：["x86"] 。 2. 键值对标签（label2）：["region=cn-north-4"]。

• jobs.<job_id>.container

  镜像配置定义。使用jobs.<job_id>.container在宿主节点上拉取并启动指定的Docker容器作为任务的运行时环境。

  表10 规格定义

  属性	说明
  类型	object或string。
  必填	否。
  默认值	无。
  约束	仅在自定义资源池或专属资源池下生效。 必须安装Docker。 默认资源池不支持。

  

  • 此配置仅在自定义资源池 (self-hos ted) 或专属资源池 (dedicated-hosted) 场景下生效，并且必须安装 Docker。
  • 默认资源池或CCE子接入模式不支持配置此字段（系统将忽略或报错）。

  用于jobs.<job_id>.container创建容器，任务下的全量步骤在该环境下执行。如果某些步骤同时使用了脚本操作和容器操作，则这些容器操作将作为同级容器在同一网络上运行，并具有相同的卷挂载点。如果不设置，则所有步骤都将直接在runs-on指定的执行机上运行。

  • 在容器内运行任务

    name: CI
    on:
      push:
        branches: [ main ]
    jobs:
      container-test-job:
        runs-on: ubuntu-latest
        container:
          image: node:18
          env:
            NODE_ENV: development
          ports:
            - 80
          volumes:
            - my_docker_volume:/volume_mount
          options: --cpus 1
        steps:
          - name: Check for dockerenv file
            run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

  • 只指定容器镜像。如果只指定容器镜像，则可以省略image关键字。

    jobs:
      container-test-job:
        runs-on: ubuntu-latest
        container: node:18

  1. jobs.<job_id>.container.image

     使用jobs.<job_id>.container.image定义运行操作时使用的Docker镜像。该值可以是Docker Hub镜像名称或镜像仓库名称。

     表11 规格定义

     属性	说明
     类型	string。
     必填	是（当container为object时必填）。
     默认值	无。
     约束	Docker Hub镜像名称或镜像仓库名称。支持带标签（如node:18）。

  2. jobs.<job_id>.container.credentials

     如果镜像的容器注册表需要身份验证才能拉取镜像，您可以使用jobs.<job_id>.container.credentials来设置and map。

     表12 规格定义

     属性	说明
     类型	object。
     必填	否。
     默认值	无。
     约束	包含username和password字段。建议使用secrets引用敏感信息。

     • 为容器注册表定义凭据

     container:
       image: ghcr.io/owner/image
       credentials:
          username: ${{ github.actor }}
          password: ${{ secrets.github_token }}

  3. jobs.<job_id>.container.env
     用于在容器中设置环境变量。

     表13 规格定义

     属性	说明
     类型	object。
     必填	否。
     默认值	无。
     约束	变量名仅支持包含字母、数字、下划线，且不能以数字开头。

  4. jobs.<job_id>.container.ports
     用于设置array容器上要暴露的端口列表。

     表14 规格定义

     属性	说明
     类型	array[number]。
     必填	否。
     默认值	无。
     约束	端口范围为1-65535。

  5. jobs.<job_id>.container.volumes

     用于设置array容器要使用的卷。通过使用卷，可以实现在服务之间或任务中的其他步骤之间共享数据。您可以指定命名Docker卷、匿名Docker卷或主机上的绑定挂载。

     表15 规格定义

     属性	说明
     类型	array[string]。
     必填	否。
     默认值	无。
     约束	格式：<source>:<destinationPath>。 source：卷名或绝对路径。 destinationPath：容器内绝对路径。

     

     指定卷需要指定源路径和目标路径。

     • 在容器中挂载卷

     volumes:
       - my_docker_volume:/volume_mount
       - /data/my_data
       - /source/directory:/destination/directory

  6. jobs.<job_id>.container.options

     用于配置其他Docker容器资源选项。

     表16 规格定义

     属性	说明
     类型	string。
     必填	否。
     默认值	无。
     约束	Docker容器选项，不支持--network和--entrypoint选项。

     • 使用自定义镜像在自定义资源池执行配置示例

     jobs:
       job_name:
         runs-on:
           group: my-private-pool
           labels: [x86,region=cn-north-4]
         
         container:
           source: swr
           image: my-org/java-build-env:v2.0
           env:                          # 传递给容器的环境变量
             NODE_ENV: production
           ports:                        # 端口映射（较少用，多用于 service 容器）
             - 8080:80
           volumes:                      # 挂载宿主机的额外目录到容器
             - my_docker_volume:/volume_mount
           options: --cpus 1             # 传递给底层的 `docker create` 额外命令行参数
           credentials:                  # 如果是私有镜像库，需要提供认证信息
             username: ${{ atomgit.actor }}
             password: ${{ secrets.swr_token }}
           
           resources:                    
             limits:                     # 限制容器最大使用 8核 16G
               cpu: 8
               memory: 16G
             requests:
               cpu: 4
               memory: 8G
         
         steps:
           - run: mvn clean package