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

Updated on 2025-08-06 GMT+08:00

View PDF

Syntax Guide to YAML File Configuration

Sample Code for Single-task Build

---
version: 2.0

#Parameters are specified in pairs, with a name and a corresponding value. If no value is assigned to a parameter, it will default to an empty string. When referencing a parameter, use the syntax ${parameter name}.
params:
  - name: machineArch
    value: X86

#(Optional) Configure either env or envs to set up the build environment. Use envs if you need to specify conditions 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	YAML file version specified with 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 to a parameter, it will default to an empty string. When referencing a parameter, use the syntax ${parameter name}. In the preceding sample code, the defined parameter is referenced as an input parameter by following the format ${machineArch}. When used as a condition, the declared parameter name machineArch is applied. name: Parameter name. value: The value paired with the parameter name.	No
env	Map	This build environment configuration serves the same purpose as envs. You can configure either of them. However, env does not support condition statements. For details, see the example in Configuring the Build Environment. 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) Build executor specifications. The value 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 applicable when the agent pool type (type) is set to docker. The default value is 2U8G. If you need different specifications, purchase the concurrent execution packages that match those specifications. pool: (Optional) Agent pool name. This parameter is applicable when the agent pool type (type) is set to custom.	No
envs	Map	This build environment configuration serves the same purpose as env. You can configure either of them. Unlike env, envs supports condition statements, allowing for more flexible usage of the same YAML file in different scenarios. condition: The statement allows you to specify environment information based on certain conditions. The corresponding environment settings from the resource configuration will be applied 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) Build executor specifications. The value 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 (type) is set to docker. The default value is 2U8G. If you need different specifications, purchase the concurrent execution packages that match those specifications. pool: (Optional) Agent pool name. This parameter is required when the agent pool type (type) is set to custom.	No
steps	Map	A collection of build actions. This parameter configures the build process by specifying: PRE_BUILD: defines build preparations, typically code downloads before the actual build process begins. BUILD: defines and runs service-specific build tasks.	Yes
steps: PRE_BUILD	Map	This parameter defines build preparations, typically code downloads before the actual build process begins. Currently, only checkout, manifest_checkout, and sh are supported. Generally, you only need to configure one of them. checkout: Single-repo download. For details, see the example in Build with Code (Downloading Code from a Single Repo). name: (Optional) Build action name. You can assign a custom value. If not specified, the value defaults to checkout. inputs: (Mandatory) Action input parameters. 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 used to pull code. 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. commit: (Optional) Commit ID specified for 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 specified for the build process. If both a commit ID and a tag are provided, the build will prioritize the commit ID and run based on it. path: (Optional) Subdirectory for cloning. The code is downloaded to the subdirectory. manifest_checkout: Multi-repo download. For details, see the example in Build with Code (Downloading Code from Multiple Repos via Manifest). name: (Optional) Build action name. You can assign a custom value. If not specified, the value defaults to manifest_checkout. inputs: (Mandatory) Action input parameters. These parameters vary for each action. For details, see Build Actions. manifest_url: (Mandatory) Address of a manifest repository that includes one or more XML files. 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. This path is relative to the working directory, so it cannot start with a forward slash (/) or contain any periods (.). 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) Action input parameters. 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 parameter defines and runs service-specific build tasks. Only a particular set of build actions are supported and can be flexibly combined to meet service requirements. For details about the build actions, see Selecting Build Actions. maven: defines the Maven build action. name: (Optional) Build action name. You can assign a custom value. If not specified, the value defaults to Build with Maven. image: (Mandatory) Container image used for the build. You can customize an image or use the default one. The default image name follows the format cloudbuild@Tool version. For details about the tool version, see Build Tools and Versions. inputs: (Mandatory) Action input parameters. 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. 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) Action input parameters. These parameters vary for each action. For details, see Build Actions. path: (Mandatory) Path and name of the file to be uploaded. You can use wildcard characters. version: (Optional) The default value is the build ID. name: (Optional) File name. The default value is the original file name.	Yes

Multi-task Build

---
version: 2.0

#Parameters are specified in pairs, with a name and a corresponding value. If no value is assigned to a parameter, it will default to an empty string. When referencing 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 to set up the build environment. Use envs if you need to specify conditions 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. Use buildflows if you need to specify conditions 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	YAML file version specified with 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 to a parameter, it will default to an empty string. When referencing a parameter, use the syntax ${parameter name}. In the preceding sample code, the defined parameter is referenced as an input parameter by following the format ${machineArch}. When used as a condition, the declared parameter name machineArch is applied. name: Parameter name. value: The value paired with the parameter name.	No
env	Map	This build environment configuration serves the same purpose as envs. You can configure either of them. However, env does not support condition statements. 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) Build executor specifications. The value 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 applicable when the agent pool type (type) is set to docker. The default value is 2U8G. If you need different specifications, purchase the concurrent execution packages that match those specifications. pool: (Optional) Agent pool name. This parameter is applicable when the agent pool type (type) is set to custom.	No
envs	Map	This build environment configuration serves the same purpose as env. You can configure either of them. Unlike env, envs supports condition statements, allowing for more flexible usage of the same YAML file in different scenarios. condition: The statement allows you to specify environment information based on certain conditions. The corresponding environment settings from the resource configuration will be applied 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) Build executor specifications. The value 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 (type) is set to docker. The default value is 2U8G. If you need different specifications, purchase the concurrent execution packages that match those specifications. pool: (Optional) Agent pool name. This parameter is required when the agent pool type (type) is set to custom.	No
buildflow	Map	A build job (referring to the build task on the GUI) 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 jobs that depend on each other across multiple machines. In certain scenarios, you may need to set up 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 concurrently 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) A collection of orchestrated jobs. This item defines the dependency between jobs (sub-tasks). job: (Mandatory) Name of a job. 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 (relative to the root directory of the repository) of the YAML file used for building the current job. The YAML file is a complete standalone file that can be executed for the build process. For details, see Sample Code for Single-task Build. job: (Mandatory) Name of a job. build_ref: (Mandatory) Path (relative to the repository root directory) of the YAML file used for building the current job. job: (Mandatory) Name of a job. build_ref: (Mandatory) Path (relative to the repository root directory) of the YAML file used for building the current job.	Yes
buildflows	Map	Configure buildflows if you need to specify conditions. Adapt to different service scenarios for a better use of YAML files. condition: The statement placed under buildflows allows you to specify job configurations based on certain conditions. The corresponding jobs configuration will be applied if the current condition is met. jobs: (Mandatory) A collection of orchestrated jobs. This item defines the dependency between jobs (sub-tasks). job: (Mandatory) Name of a job. build_ref: (Mandatory) Path (relative to the root directory of the repository) of the YAML file used for building the current job. The YAML file is a complete standalone file that can be executed for the build process. For details, see Sample Code for Single-task Build. params: (Optional) Parameters defined by a job. These parameters are scoped to the YAML file referenced by jobs, allowing them to be referenced within the YAML file used by jobs. name: Parameter name. value: The value paired with the parameter name. condition: The statement allows you to specify job configurations based on certain conditions. The corresponding job configuration will be applied if the current condition is met. job: (Mandatory) Name of a job. build_ref: (Mandatory) Path (relative to the repository root directory) of the YAML file used for building the current job. params: (Optional) Parameters defined by a job. These parameters are scoped to the YAML file referenced by jobs. name: Parameter name. value: The value paired with the parameter name. job: (Mandatory) Name of a job. 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 (relative to the repository root directory) of the YAML file used for building the current job.	Yes