Defining a Build Task with Code

Preparations

• Obtain permissions for CodeArts Repo.
• by referring to CodeArts Repo User Guide > "Creating a CodeArts Repo Repository".
• Create a CodeArts project by referring to CodeArts User Guide > "Preparations" > "Creating a Project".

  If you already have a project available, skip this step.

Creating a YAML File for Your Code-based Build

1. Access the CodeArts Build Homepage from the project list.
2. In the navigation pane, choose Code > Repo.
3. On the CodeArts Repo console, click New Repository. On the displayed page, select Common and click Next. Then set parameters according to Table 1, and click OK.

   Table 1 Creating a code repository

   Parameter	Description
   Repository Name	Assign a custom name to the code repository, for example, maven_yml_build. The name starts with a digit, letter, or underscore (_). The name can contain periods (.) and hyphens (-). The name cannot end with .git, .atom, or a period (.).
   Description	Optional. Enter additional information to describe the code repository.
   .gitignore Programming Language	Optional. Select the appropriate programming language, such as Java, for the .gitignore file.
   Initial Settings	Select all. Generate README: Select this option to create a README file where you can add details about the project's architecture and purpose, similar to a repository-wide comment. Automatically create check task (free of charge): Select this option to auto-generate a code check task for the repository upon creation. The check task will appear in the check task list.
   Visibility	Select Private. Private: Only repository members can access and commit code. Public: The repository is open and read-only to all guests, but is not displayed in their repository list or search results. You can select an open-source license as the remarks.

4. Choose Create > Create Directory to create a directory named .cloudbuild.
5. In the .cloudbuild directory, choose Create > Create File to create a file named build.yml. Figure 1 shows the directory that stores files of the code repository.
   Figure 1 Directory
   

   If the YAML file is not stored in the .cloudbuild directory, you can use parameter CB_BUILD_YAML_PATH to specify the path of the YAML file in the code repository. For details about parameter settings, see Adding Custom Parameters.

6. Click and write the build.yml file by referring to the following sample code.

   The following example uses a built-in x86 executor with 8 vCPUs and 16 GB memory. The tasks involve compiling and building code from CodeArts Repo using Maven, and then uploading the resulting software package to a release repo.

   For details about the sample code of different build actions, see the "Build as Code" part of each build action in Configuring a Build Task. For details about the YAML file structure of multiple tasks, see Understanding the YAML File Structure for Multiple Tasks.

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

   version: 2.0 # The version number is a mandatory and unique parameter that must be set to 2.0. params: # Build parameters that can be referenced during your build. If no build parameters are set here, parameters created during task configuration are preferentially used. - name: paramA value: valueA - name: paramB value: valueB env: # Optional. It defines the build environment. x86 is used by default if neither env or envs is set. resource: type: docker # 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: X86 # The host type of the build environment can be either x86 or Arm. class: 8 vCPUs | 16 GB # The specification can be: 2 vCPUs | 8 GB, 4 vCPUs | 8 GB, 8 vCPUs | 16 GB, 16 vCPUs | 32 GB, or 16 vCPUs | 64 GB. This parameter is not required when the agent pool type is set to a custom one. pool: Mydocker #Agent pool name. This parameter is required when the agent pool type is set to a custom one. steps: PRE_BUILD: # It prepares for the build process by performing tasks such as downloading code and running shell commands. - checkout: name: Code download # Optional inputs: # Action parameters scm: codehub # Code source: CodeArts Repo only url: xxxxxxxxx # This refers to the SSH address of the repository that the code is pulled from. branch: ${codeBranch} # Pulled code branch, which can be parameterized. - sh: inputs: command: echo ${paramA} BUILD: # It defines the build action. Only one BUILD can be configured. - maven: # Action keyword. Only specified keywords are supported. name: maven build # Optional image: xxx # Image address. inputs: command: mvn clean package - upload_artifact: inputs: path: "**/target/*.?ar"

Configuring Basic Information

1. In the navigation pane, choose CICD > Build.
2. Click Create Task. On the displayed page, configure the basic information of the build task by referring to Table 2. Click Next. The page for selecting a build template is displayed.

   Table 2 Basic information

   Parameter	Description
   Name	Assign a custom name to the build task. Letters, digits, underscores (_), and hyphens (-) allowed. 1 to 115 characters.
   Project	Select the project to which the build task belongs. This parameter is autofilled when you access CodeArts Build through the project list, so you can leave it as default. When accessing the service through the service homepage, select the project created in preparations.
   Code Source	If you select Repo, code is pulled from CodeArts Repo for your build.
   Repository	Select the repository from where the code to be compiled is pulled.
   Default Branch	Select a default branch.
   Description	Optional. Enter additional information to describe the build task. Max. 512 characters.

Selecting a Build Template

On the page for selecting a build template, select Blank Template and click OK. The Build Actions page is displayed.

No matter which build template you select, code-based builds remain unaffected.

Configuring Build Actions

In the upper left corner of the Build Actions page, click the Code tab. The system automatically reads the YAML file from the code repository and the branch configured in basic information.

You can modify the YAML file by referring to the sample code in the "Build as Code" part of build task configurations. Any changes made to the YAML file will overwrite the original YAML file you create for your code-based build once the build task is completed.

Complete all the configurations and click Save to create a build task.

Understanding the YAML File Structure for Multiple Tasks

A build task 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.
• 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 BuildFlow, which organizes multiple build tasks in a directed acyclic graph (DAG) and runs them in parallel based on their dependencies.

The following is a YAML file example for multiple tasks:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

version: 2.0 # The version number is a mandatory and unique parameter that must be set to 2.0.
params: # Build parameters, which can be referenced during a build.
  - name: p
    value: 1
# env and envs are optional. Configure envs if you need a condition to determine the host specification and type.
env: # This parameter takes precedence once being set. The host specification and type defined here will be used instead of the ones set in the build environment configuration.
  resource:
    type:docker # 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:X86 # The host type of the build environment can be either x86 or Arm.
    class:8 vCPUs | 16 GB # The specification can be: 2 vCPUs | 8 GB, 4 vCPUs | 8 GB, 8 vCPUs | 16 GB, 16 vCPUs | 32 GB, or 16 vCPUs | 64 GB. This parameter is not required when the agent pool type is set to a custom one.
    pool:Mydocker #Agent pool name. This parameter is required when the agent pool type is set to a custom one.
envs: 
    - condition: p == 1 # The following host specification and type are used if this condition is met.
      resource:
        type: docker 
        arch: ARM
    - condition: p == 0 # The following host specification and type are not used if this condition is not met.
      resource:
        type: docker
        arch: X86
# Configure either buildflow or buildflows. Configure buildflows if you need a condition to control job executions.
buildflow:
 strategy: lazy # Define the running policy of buildflow, which can be lazy or eager. The eager mode is used by default if this parameter is not defined.
    jobs: # Build tasks
      - job: Job3 # Assign a custom name to the child task.
        depends_on: # Define the task dependency. In this practice, the configuration indicates that Job3 depends on Job1 and Job2.
            - Job1
            - Job2
        build_ref: .cloudbuild/build3.yml # Define the YAML build script to run during a job build.
      - job: Job1
        build_ref: .cloudbuild/build1.yml
      - job: Job2
        build_ref: .cloudbuild/build2.yml
buildflows:
  - condition: p == 1 # All jobs under this collection are executed if this condition is met.
    jobs: # It defines the tasks to be orchestrated.
      - job: Job1 # Assign a custom name to the child task.
        build_ref: 1.yml # YAML build script that needs to be run during a build.
        params:
          - name: abc
            value: 123
      - condition: p == 1 # Job2 is executed if this condition is met.
        job: Job2
        build_ref: 2.yml
        params:
          - name: abc
            value: 123

• lazy: A job with a higher priority is triggered first. After successful execution, a job with a lower priority is then triggered. The build takes a long time but saves resources. Therefore, you are advised to use this method when the number of parallel jobs is insufficient.
• eager: All jobs are triggered synchronously. For jobs that depend on other jobs, prepare the environment and code first and wait until the dependency jobs are successfully executed. Resources may be idle, but the build time can be shortened. You are advised to use this mode when the parallel job quota is sufficient.

jobs

jobs is used to define jobs to be orchestrated. Each job must have a unique name as its identifier. If job A depends on job B, B has a higher priority. Jobs with the same priority are triggered synchronously.

The following is a code sample:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

    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

As shown in the preceding example, Job3 depends on and has lower priority than Job1 and Job2, which are triggered synchronously.

params

params can define global parameters to be shared by all jobs. You can also define parameters only for some jobs. Here is an example.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

buildflow:
    jobs:
      - job: Job3
        depends_on:
            - Build Job1
            - Build job2
        build_ref: .cloudbuild/build3.yml
      - job: Job1
        params:
          - name: isSubmodule
            value: true
        build_ref: .cloudbuild/build1.yml
      - job: Job2
        params:
          - name: isSubmodule
            value: true
        build_ref: .cloudbuild/build2.yml

As shown in the preceding example, global parameters (params) are not defined. Instead, the isSubmodule parameter is defined in Job1 and Job2.

During a build with YAML, parameters are used in the following priority (as shown in the preceding sample code):

Runtime parameters configured on the Parameters page > Default values of parameters configured on the Parameters page > Parameters defined in build_ref > Parameters defined in params under a job > Global parameters defined in params under BuildFlow