Defining a Build Task with Code
CodeArts Build allows you to define your build as code using YAML. Your configurations, such as build environments, parameters, commands, and actions, reside in a YAML file named build.yml. After creating this file, add it along with the source code to a code repository. The file will be used as a script by the system to run a build.
Defining your build as code has the following advantages:
- Your YAML file collects and clearly describes build parameters, commands, steps, as well as post-build operations, ensuring a trusted build process.
- The build configurations in build.yml are versioned alongside the commits in the code repository. This enables you to rerun earlier build tasks despite configuration changes.
- To modify the build script for a new feature, create a branch to modify the build.yml file for testing. By this way, you will not have to worry about affecting other branches.
You can only use the code hosted in CodeArts Repo for code-based builds.
Preparations
- You have 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
- Access the CodeArts Build Homepage from the project list.
- In the navigation pane, choose .
- 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 .gitignore file based on the programming language being used, such as Java.
Initial Settings
Select all.
- Allow project members to access the repository: Select this option to auto-assign a project manager as the repository administrator, and a developer as a common repository member. Once these roles are added to the project, they will be automatically synced with existing repositories.
- 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.
- Choose .cloudbuild. to create a directory named
- In the .cloudbuild directory, choose to create a file named build.yml. Figure 1 shows the directory that stores files of the code repository.
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.
- 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
- In the navigation pane, choose .
- 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
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 the 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
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot