Help Center/ CodeArts Build/ User Guide/ References/ YAML File Syntax Configuration

Updated on 2024-12-02 GMT+08:00

View PDF

YAML File Syntax Configuration

Single-task Build

---
version: 2.0

# Parameter definition should be done in pairs, with a name and a value. If no value is assigned, an empty string will be used by default. To reference a parameter, use the syntax ${parameter name}.
params:
  - name: machineArch
    value: X86

# (Optional) Configure either env or envs. Configure envs if you need a condition to determine the host specification and type.
env:
  resource:
    type: docker
    arch: X86
    class: 8U16G
    pool: Mydocker

envs:
  - condition: machineArch == 'ARM'
    resource:
      type: docker 
      arch: ARM
  - condition: machineArch == 'X86'
    resource:
      type: docker
      arch: X86

#Build actions
steps:
  PRE_BUILD:
    - checkout:
        name: checkout
        inputs:
          scm: codehub
          url: git@codehub.devcloud.cn-north-7.ulanqab.huawei.com:huang-test00001/maven.git
          branch: master
          commit: commitId
          lfs: true
          submodule: true
          depth: 100
          tag: tag
          path: test
    - manifest_checkout:
        name: "manifest"
        inputs:
          manifest_url: https://codehub.devcloud.xxxxxxx.ulanqab.huawei.com/IPD-xxxxxx/manifest.git
          manifest_branch: master
          manifest_file: default.xml
          path: dir/dir02
          lfs: true
          repo_url: https://codehub.devcloud.xxxxxxx.ulanqab.huawei.com/IPD-xxxxxx/git-repo.git
          repo_branch: master
          username: someone
          password: PASSWD
    - sh:
        inputs:
          command: echo ${machineArch}

  BUILD: # Build actions
    - maven:
        name: Build with Maven
        image: cloudbuild@maven3.5.3-jdk8-open
        inputs:
          settings:
            public_repos:
              - https://mirrors.huawei.com/maven
          cache: true
          unit_test:
            coverage: true
            ignore_errors: false
            report_path: "**/TEST*.xml"
            enable: true
            coverage_report_path: "**/site/jacoco"
          command: mvn package -Dmaven.test.failure.ignore=true -U -e -X -B
          check:
            project_dir: ./
            settings: ~/.m2/settings.xml
            param: ''
    - upload_artifact:
        inputs:
          path: "**/target/*.?ar"
          version: 2.1
          name: packageName

**Table 1** Single-task syntax configuration
Parameter	Type	Description	Mandatory
version	String	Specify the YAML file version, which is a fixed value. Currently, the only supported version is 2.0.	Yes
params	Map	Global parameter configuration. These parameters must be specified in pairs, with a name and a corresponding value. If no value is assigned, the parameter is considered an empty string by default. When referencing a parameter, use the syntax ${parameter name}. In the preceding code snippet, the defined parameter is referenced as an input parameter by following the format ${machineArch}. When the parameter is used as a condition, the declared parameter name machineArch is used. name: Parameter name. value: The value paired with the parameter name.	No
env	Map	Build environment configuration, which serves the same purpose as envs. You can configure either of them. However, condition statements are not supported. resource: Build environment resource information. type: (Mandatory) Agent pool type. The value can be docker or custom. docker indicates that the default executor is used, and custom indicates that a custom executor is used. arch: (Mandatory) Build executor architecture. The value can be either x86 or Arm. class: (Optional) The specification can be: 2U8G (2 vCPUs \| 8 GB), 4U8G (4 vCPUs \| 8 GB), 8U16G (8 vCPUs \| 16 GB), 16U32G (16 vCPUs \| 32 GB), or 16U64G (16 vCPUs \| 64 GB). This parameter takes effect when the agent pool type is set to a docker one. The default value is 2U8G. If you need different specifications, you need to purchase the parallel execution packages that match those specifications. pool: (Optional) Agent pool name. This parameter is required when the agent pool type is set to a custom one.	No
envs	Map	This build environment configuration item serves the same purpose as env. Either of them can be configured. The condition statement is supported, allowing for more flexible usage of the same YAML file in different scenarios. condition: Condition statement. The corresponding environment information from the resource configuration is used if the current condition is met. resource: Build environment resource information. type: (Mandatory) Agent pool type. The value can be docker or custom. docker indicates that the default executor is used, and custom indicates that a custom executor is used. arch: (Mandatory) Build executor architecture. The value can be either x86 or Arm. class: (Optional) The specification can be: 2U8G (2 vCPUs \| 8 GB), 4U8G (4 vCPUs \| 8 GB), 8U16G (8 vCPUs \| 16 GB), 16U32G (16 vCPUs \| 32 GB), or 16U64G (16 vCPUs \| 64 GB). This parameter is required when the agent pool type is set to a docker one. The default value is 2U8G. If you need different specifications, you need to purchase the parallel execution packages that match those specifications. pool: (Optional) Agent pool name. This parameter is required when the agent pool type is set to a custom one.	No
steps	Map	Build action executions. This item is used to configure the build process, including the tasks for build preparations and executions. PRE_BUILD: specifies build preparations. This item is generally used to configure code downloads before the actual build process begins. BUILD: specifies build tasks. This item is used to run service-related build tasks.	Yes
steps: PRE_BUILD	Map	This item specifies build preparations and is generally used to configure code downloads before the actual build process begins. Currently, it supports checkout, manifest_checkout, and sh. Typically, you only need to configure one of them. checkout: Single-repo download. name: (Optional) Build action name, which can be customized. The default value is Code Checkout. inputs: (Mandatory) Input parameters of the action. These parameters vary for each action. For details, see Build Actions. scm: (Optional) Code source. The supported code source is currently limited to codehub, which is also the default value. url: (Mandatory) SSH or HTTPS address of code to be pull. SSH (ssh) is used when code is pulled from CodeArts Repo (codehub), and HTTPS (https) is used for other code sources. branch: (Mandatory) Name of the code branch to be pulled. commitId: (Optional) Commit ID obtained during the build process. lfs: (Optional) Whether to enable git lfs. The default value is false. submodule: (Optional) Whether to pull submodules. The default value is false. depth: (Optional) Shallow clone depth. When a commit ID is specified for builds, depth must be greater than or equal to the depth of the commit ID. The default value is 1. tag: (Optional) Tag pulled during tag builds: If a commit ID and a tag exist at the same time, the build based on a commit ID is executed first. path: (Optional) Sub-path for cloning. The code is downloaded to the subpath. manifest_checkout: Multi-repo download. name: (Optional) Build action name, which can be customized. The default value is manifest_checkout. inputs: (Mandatory) Input parameters of the action. These parameters vary for each action. For details, see Build Actions. manifest_url: (Optional) Address of a Manifest repository that includes an XML file. manifest_branch: (Optional) The specified manifest branch or revision. The default value is HEAD. manifest_file: (Optional) Path of the manifest file. The defined repositories must be of the same code source. The default value is default.xml. path: (Optional) The download path for all sub-repositories of the manifest file. This path is the relative path of the working directory, so it cannot start with / and cannot contain .. The default value is the current working directory. lfs: (Optional) Whether to enable git lfs. The default value is false. repo_url: (Optional) Repository address. repo_branch: (Optional) Repository branch. The default value is stable. username: (Optional) Username used for downloading the repository. This parameter is required for private repositories. password: (Optional) Password used for downloading the repository. This parameter is required for private repositories. sh: Run Shell commands inputs: (Mandatory) Input parameters of the action. These parameters vary for each action. For details, see Build Actions. command: (Mandatory) Configuration for running shell commands. If checkout or manifest_checkout cannot meet service requirements, you can customize shell commands to prepare for the build.	Yes
steps: BUILD	Map	This item specifies build tasks and is used to run service-related build tasks. Only specific build actions are supported. The build actions can be flexibly combined based on service requirements. For details about the build actions, see Selecting Build Actions. maven: defines the Maven build action. name: (Optional) Build action name, which can be customized. The default value is Build with Maven. image: (Mandatory) Container image used for the build. You can customize an image or use the default image. The default image name follows the format cloudbuild@Tool version. For details about the tool version, see . inputs: (Mandatory) Input parameters of the action. These parameters vary for each action. For details, see Build Actions. settings: (Optional) The settings file configuration used for the Maven build. public_repos: Addresses of the repositories from which the dependency packages are downloaded. https://mirrors.huawei.com/maven cache: (Optional) Whether to enable the cache. The default value is false. unit_test: (Optional) Unit test configuration. coverage: (Optional) Whether to process coverage data. The default value is false. ignore_errors: (Optional) Whether to ignore unit test errors. The default value is true. report_path: (Mandatory) Unit test data path. enable: (Optional) Whether to process unit test data. The default value is true. coverage_report_path: (Optional) Coverage data path. command: (Mandatory) Build command. check: (Optional) Check configuration. project_dir: (Mandatory) Project path. settings: (Optional) Path of the settings file used for the Maven build. param: (Optional) Maven parameter. upload_artifact: defines the action of uploading the binary package to the artifact repository. inputs: (Mandatory) Input parameters of the action. These parameters vary for each action. For details, see Build Actions. path: (Mandatory) Path and name of the file to be uploaded. Wildcard characters are supported. version: (Optional) The default value is the build ID. name: (Optional) File name. The default value is the original file name.

Multi-task Build

---
version: 2.0

# Parameter definition should be done in pairs, with a name and a value. If no value is assigned, an empty string will be used by default. To reference a parameter, use the syntax ${parameter name}.
params:
  - name: machineArch
    value: X86
  - name: jobCondition
    value: 1
  - name: jobsCondition
    value: 1

# (Optional) Configure either env or envs. Configure envs if you need a condition to determine the host specification and type.
env:
  resource:
    type: docker
    arch: X86
    class: 8U16G
    pool: Mydocker
envs: 
  - condition: machineArch == 'ARM'
    resource:
      type: docker 
      arch: ARM
  - condition: machineArch == 'X86'
    resource:
      type: docker
      arch: X86

# Configure either buildflow or buildflows. Configure buildflows if you need a condition to control job executions.
buildflow:
  strategy: Lazy
    jobs:
      - job: Job3
        depends_on:
          - Job1
          - Job2
        build_ref: .cloudbuild/build3.yml
      - job: Job1
        build_ref: .cloudbuild/build1.yml
      - job: Job2
        build_ref: .cloudbuild/build2.yml
buildflows:
  - condition: jobsCondition == 1
    jobs:
      - job: Job1
        build_ref: .cloudbuild/build1.yml
        params:
          - name: job1Params
            value: 1
      - condition: jobCondition == 1
        job: Job2
        build_ref: .cloudbuild/build2.yml
        params:
          - name: job2Params
            value: 2
      - job: Job3
        depends_on:
          - Job1
          - Job2
        build_ref: .cloudbuild/build3.yml
  - condition: jobsCondition == 2
    jobs:
      - job: Job3
        build_ref: .cloudbuild/build3.yml

**Table 2** Multi-task syntax configuration
Parameter	Type	Description	Mandatory
version	String	Specify the YAML file version, which is a fixed value. Currently, the only supported version is 2.0.	Yes
params	Map	Global parameter configuration. These parameters must be specified in pairs, with a name and a corresponding value. If no value is assigned, the parameter is considered an empty string by default. When referencing a parameter, use the syntax ${parameter name}. In the preceding code snippet, the defined parameter is referenced as an input parameter by following the format ${machineArch}. When the parameter is used as a condition, the declared parameter name machineArch is used. name: Parameter name. value: The value paired with the parameter name.	No
env	Map	Build environment configuration, which serves the same purpose as envs. You can configure either of them. However, condition statements are not supported. resource: Build environment resource information. type: (Mandatory) Agent pool type. The value can be docker or custom. docker indicates that the default executor is used, and custom indicates that a custom executor is used. arch: (Mandatory) Build executor architecture. The value can be either x86 or Arm. class: (Optional) The specification can be: 2U8G (2 vCPUs \| 8 GB), 4U8G (4 vCPUs \| 8 GB), 8U16G (8 vCPUs \| 16 GB), 16U32G (16 vCPUs \| 32 GB), or 16U64G (16 vCPUs \| 64 GB). This parameter takes effect when the agent pool type is set to a docker one. The default value is 2U8G. If you need different specifications, you need to purchase the parallel execution packages that match those specifications. pool: (Optional) Agent pool name. This parameter is required when the agent pool type is set to a custom one.	No
envs	Map	This build environment configuration item serves the same purpose as env. Either of them can be configured. The condition statement is supported, allowing for more flexible usage of the same YAML file in different scenarios. condition: Condition statement. The corresponding environment information from the resource configuration is used if the current condition is met. resource: Build environment resource information. type: (Mandatory) Agent pool type. The value can be docker or custom. docker indicates that the default executor is used, and custom indicates that a custom executor is used. arch: (Mandatory) Build executor architecture. The value can be either x86 or Arm. class: (Optional) The specification can be: 2U8G (2 vCPUs \| 8 GB), 4U8G (4 vCPUs \| 8 GB), 8U16G (8 vCPUs \| 16 GB), 16U32G (16 vCPUs \| 32 GB), or 16U64G (16 vCPUs \| 64 GB). This parameter is required when the agent pool type is set to a docker one. The default value is 2U8G. If you need different specifications, you need to purchase the parallel execution packages that match those specifications. pool: (Optional) Agent pool name. This parameter is required when the agent pool type is set to a custom one.	No
buildflow	Map	A build job is the smallest unit that a build project can be broken down into for simple service scenarios. However, for more complex requirements, you may need to use a multi-repo approach to distribute build tasks that depend on each other across multiple machines. In certain scenarios, you may need to break down a build job to multiple build tasks in a modular and fine-grained way, and run them in a specific order. Each task depends on the successful completion of its dependency task. To handle such complex builds, CodeArts Build offers a task model called BuildFlow, which organizes multiple build jobs in a directed acyclic graph (DAG) and runs them in parallel with the maximum capacity based on job dependencies. By doing so, CodeArts Build helps improve build efficiency. strategy: (Optional) buildflow running policy. The value can be either Lazy or Eager. Lazy: The build takes a long time but saves resources. Therefore, you are advised to use this method when the agent pool is limited. This method triggers jobs with higher priority. Eager: Resources may be idle, but the build time can be shortened. You are advised to use this method when the agent pool quota is sufficient. This method triggers the all jobs at the same time. The default value is Eager. jobs: (Mandatory) Job orchestration. This item defines the dependency between jobs (sub-tasks). job: (Mandatory) Name of a job, which is a sub-task. depends_on: (Optional) Whether a job depends on other jobs. Enter the name of the dependency jobs. The current job depends on Job1 and Job2. build_ref: (Mandatory) Path of the YAML file used for building the current job (relative to the root directory of the repository). The YAML file is a complete standalone file that can be executed for the build process. For details, see Single-task Build. job: (Mandatory) Name of a job, which is a sub-task. build_ref: (Mandatory) Path of the YAML file used for building the current job (relative to the repository root directory). job: (Mandatory) Name of a job, which is a sub-task. build_ref: (Mandatory) Path of the YAML file used for building the current job (relative to the repository root directory).
buildflows	Map	Configure buildflows if you need a condition to control job executions. Adapt to different service scenarios for a better use of YAML files. condition: Condition statement. The corresponding jobs configuration is used if the current condition is met. The condition must be placed under buildflows. jobs: (Mandatory) Job orchestration. This item defines the dependency between jobs (sub-tasks). job: (Mandatory) Name of a job, which is a sub-task. build_ref: (Mandatory) Path of the YAML file used for building the current job (relative to the root directory of the repository). The YAML file is a complete standalone file that can be executed for the build process. For details, see Single-task Build. params: (Optional) Parameters defined by a job. The scope of these parameters is the YAML file referenced by jobs. The parameters defined here can be referenced in the YAML file used by jobs. name: Parameter name. value: The value paired with the parameter name. condition: Condition statement. The corresponding job configuration is used if the current condition is met. job: (Mandatory) Name of a job, which is a sub-task. build_ref: (Mandatory) Path of the YAML file used for building the current job (relative to the repository root directory). params: (Optional) Parameters defined by a job. The scope of these parameters is the YAML file referenced by jobs. name: Parameter name. value: The value paired with the parameter name. job: (Mandatory) Name of a job, which is a sub-task. depends_on: (Optional) Whether a job depends on other jobs. Enter the name of the dependency jobs. The current job depends on Job1 and Job2. build_ref: (Mandatory) Path of the YAML file used for building the current job (relative to the repository root directory).