Help Center/ CodeArts Build/ API Reference/ APIs/ CodeArts Build (Out-of-date)/ Creating a Build Task (Outdated)

Updated on 2025-09-22 GMT+08:00

View PDF

Creating a Build Task (Outdated)

Function

This API is used to create a build task.

Calling Method

For details, see Calling APIs.

URI

POST /v3/jobs/create

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. (The value of the X-Subject-Token response header is the user token.) It is obtained by calling the IAM API. Constraints Global tenant tokens are not supported. Use a region-level token whose scope is project. Range N/A. Default Value N/A.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
arch	Yes	String	Definition CPU architecture of the server. Constraints N/A. Range x86-64 or arm. Default Value N/A.
project_id	Yes	String	Definition CodeArts project ID. For details about how to obtain the Constraints N/A. Range A UUID. Use a 32-character string containing a mix of digits and letters. Default Value N/A.
job_name	Yes	String	Definition Build task name. Constraints N/A. Range Letters, digits, underscores (_), and hyphens (-) are allowed. The value can contain 1 to 115 characters. Default Value N/A.
auto_update_sub_module	No	String	Definition Whether submodules are automatically updated. Constraints N/A. Range false: Submodules are not updated. true: Submodules are updated. Default Value false
flavor	No	String	Definition Executor specification. Constraints N/A. Range N/A. Default Value N/A.
host_type	No	String	Definition Host type. Constraints N/A. Range N/A. Default Value N/A.
build_config_type	No	String	Definition Build configuration type. It can be YAML or ACTION. Constraints N/A. Range YAML or ACTION. Default Value N/A.
build_if_code_updated	No	Boolean	Definition The switch that controls whether code commits trigger builds. Constraints N/A. Range true: Every code commit will trigger the build task. false: Code commits will not trigger the build task. Default Value N/A.
parameters	No	Array of CreateBuildJobParameter objects	Definition A list of build task execution parameters. Constraints N/A. Range N/A. Default Value N/A.
group_id	No	String	Definition Task group ID. Constraints N/A. Range N/A. Default Value N/A.
timeout	No	CreateBuildTimeout object	Definition Timeout duration of a build task. Constraints N/A. Range N/A. Default Value N/A.
scms	No	Array of CreateBuildJobScm objects	Definition Information about the code repository used during a build. Constraints N/A. Range N/A. Default Value N/A.
steps	Yes	Array of CreateBuildJobSteps objects	Definition Build actions being executed. Constraints N/A. Range N/A. Default Value N/A.
triggers	No	Array of Trigger objects	Definition A collection of scheduled task triggers. Constraints N/A. Range N/A. Default Value N/A.

**Table 3** CreateBuildJobParameter
Parameter	Mandatory	Type	Description
name	No	String	Definition Parameter definition name. The default value is hudson.model.StringParameterDefinition. Constraints N/A. Range N/A. Default Value N/A.
params	No	Array of CreateBuildJobParameterParam objects	Definition Subparameters of build execution parameters. Constraints N/A. Range N/A. Default Value N/A.

**Table 4** CreateBuildJobParameterParam
Parameter	Mandatory	Type	Description
name	No	String	Definition Parameter field name. Constraints N/A. Range N/A. Default Value N/A.
value	No	String	Definition Parameter field value. Constraints N/A. Range N/A. Default Value N/A.
limits	No	Array of LimitsParam objects	Definition Restrictions on enumeration parameters. Constraints N/A. Range N/A. Default Value N/A.

**Table 5** LimitsParam
Parameter	Mandatory	Type	Description
disable	No	String	Definition Whether enabled or not. The default value is 0, indicating "enabled". Constraints N/A. Range N/A. Default Value N/A.
display_name	No	String	Definition Parameter display name. Constraints N/A. Range N/A. Default Value N/A.
name	No	String	Definition Parameter name. Constraints N/A. Range N/A. Default Value N/A.

**Table 6** CreateBuildTimeout
Parameter	Mandatory	Type	Description
limit	No	String	Definition Build task execution timeout. Constraints N/A. Range 0–4. Default Value 4
unit	No	String	Definition Time unit for timeout. Constraints N/A. Range seconds, minute, or hour. Default Value hour

**Table 7** CreateBuildJobScm
Parameter	Mandatory	Type	Description
branch	No	String	Definition Name of the code branch. Constraints N/A. Range N/A. Default Value N/A.
url	Yes	String	Definition Code repository address. Constraints N/A. Range N/A. Default Value N/A.
repo_id	No	String	Definition Repo ID. Constraints N/A. Range N/A. Default Value N/A.
web_url	No	String	Definition HTTPS address of the code repository. Constraints N/A. Range N/A. Default Value N/A.
scm_type	Yes	String	Definition Repository type. Constraints N/A. Range repo, github, gitee, gerrit, gitcode, or codehub Default Value N/A.
is_auto_build	No	Boolean	Definition Whether to trigger a build upon any code commit. Constraints N/A. Range ● true: Auto-build allowed. ● false: Auto-build disallowed. Default Value true
enable_git_lfs	No	Boolean	Definition Whether to enable Git LFS. Constraints N/A. Range ● true: Git LFS enabled. ● false: Git LFS disabled. Default Value ● true
build_type	No	String	Definition Build type. Options include build from a branch, tag, or commit. Constraints N/A. Range N/A. Default Value N/A.
depth	No	String	Definition Clone depth. The clone depth is the number of recent commits that will be cloned. A larger value indicates more commits will be fetched. Constraints N/A. Range 1–25. Default Value 1
end_point_id	No	String	Definition Endpoint ID used for pulling code from services such as Git. Constraints N/A. Range N/A. Default Value N/A.
source	No	String	Definition Source of the code repository. Constraints N/A. Range N/A. Default Value N/A.
group_name	No	String	Definition Repository group name. Constraints N/A. Range N/A. Default Value N/A.
repo_name	No	String	Definition Repository name. Constraints N/A. Range N/A. Default Value N/A.

**Table 8** CreateBuildJobSteps
Parameter	Mandatory	Type	Description
properties	No	Map<String,Object>	Definition Build action parameters. Constraints N/A. Range N/A. Default Value N/A.
module_id	Yes	String	Definition Build action ID. Constraints N/A. Range N/A. Default Value N/A.
name	Yes	String	Definition Build action name. Constraints The value allows letters, digits, hyphens (-), underscores (_), commas (,), semicolons (;), colons (:), periods (.), slashes (/), and parentheses. The value can contain 1 to 128 characters. Range N/A. Default Value N/A.
version	No	String	Definition Build action version. Constraints N/A. Range N/A. Default Value N/A.
enable	No	Boolean	Definition Whether to enable automatic build task. Constraints N/A. Range ● true: Enabled. ● false: Disabled. Default Value true

**Table 9** Trigger
Parameter	Mandatory	Type	Description
parameters	Yes	Array of ParameterItem objects	Definition Custom parameter. Constraints N/A. Range N/A. Default Value N/A.
name	Yes	String	Definition Trigger type. Constraints N/A. Range N/A. Default Value N/A.

**Table 10** ParameterItem
Parameter	Mandatory	Type	Description
name	Yes	String	Definition Custom parameter name. Constraints ● Do not use the following fields: LD_PRELOAD, LD_LIBRARY_PATH, PATH, BASH_ENV, GIT_SSH_COMMAND, and path. ● Symbols are not supported. Range Custom parameter name. The length cannot exceed 128 characters. Only letters, digits, and underscores (_) are supported. Default Value N/A.
value	Yes	String	Definition Parameter value. Constraints N/A. Range Default value of the custom parameter. Max. 8,192 characters. Default Value N/A.

Response Parameters

Status code: 200

**Table 11** Response body parameters
Parameter	Type	Description
result	result object	Definition Data returned after the API is successfully called. Range N/A.
status	String	Definition Status information. Range ● success: The API call is successful. ● fail: The API call failed.
error	String	Definition Error message. Range N/A.

**Table 12** result
Parameter	Type	Description
job_id	String	Definition Build task ID. Range N/A.

Status code: 400

**Table 13** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 401

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 403

**Table 15** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 404

**Table 16** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Status code: 500

**Table 17** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Example Requests

POST https://{endpoint}/v3/jobs/create

{
  "arch" : "x86-64",
  "project_id" : "a287e712be6c404ca26e5f69040fa12b",
  "job_name" : "examplejob",
  "auto_update_sub_module" : "false",
  "flavor" : "2u8g",
  "parameters" : [ {
    "name" : "hudson.model.StringParameterDefinition",
    "params" : [ {
      "name" : "name",
      "value" : "codeBranch"
    }, {
      "name" : "type",
      "value" : "normalparam"
    }, {
      "name" : "defaultValue",
      "value" : "master"
    }, {
      "name" : "description",
      "value" : "description"
    }, {
      "name" : "deletion",
      "value" : "false"
    }, {
      "name" : "defaults",
      "value" : "true"
    }, {
      "name" : "staticVar",
      "value" : "false"
    }, {
      "name" : "sensitiveVar",
      "value" : "false"
    } ]
  } ],
  "scms" : [ {
    "branch" : "master",
    "url" : "git@codehub.devcloud.{region}.example.com:soso-test00001/an.git",
    "repo_id" : "2111746211",
    "web_url" : "https://codehub.devcloud.{region}.example.com/codehub/2111746211/home",
    "scm_type" : "codehub",
    "is_auto_build" : false,
    "build_type" : "branch",
    "depth" : "1"
  } ],
  "steps" : [ {
    "properties" : null,
    "module_id" : "devcloud2018.codeci_action_20043.action",
    "name" : "Build with Maven",
    "version" : "20231001.6",
    "enable" : true
  } ],
  "host_type" : "devcloud"
}

Example Responses

Status code: 200

{
  "result" : {
    "job_id" : "db8467d972cc47f7a1bd2a3a3e77596a"
  },
  "error" : null,
  "status" : "success"
}

Status Codes

Status Code	Description
200	OK
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

Error Codes

See Error Codes.

Parent topic: CodeArts Build (Out-of-date)

Previous topic: Enabling a Build Task

Next topic: Updating a Build Task (Outdated)

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel