A pipeline job defines a unit of work within a stage. Each job runs in its own build environment and consists of either multiple steps that share a workspace, or a single component call. Use jobs to organize build, test, and deployment tasks across pipeline stages.
YAML schema
The following YAML block shows all available job properties. Required properties are marked with comments.
stages:
<stage_id>:
jobs:
<job_id>: # Required. Unique job identifier.
name: string # Display name. Defaults to job_id.
runsOn: # Execution environment.
group: string # Build cluster identifier.
container: string # Container image (specified container environment).
labels: string # Scheduling labels (default VM environment).
vm: boolean # Set to true for VM mode.
instanceType: string # Resource specification: SMALL_1C2G | MEDIUM_2C4G | LARGE_4C8G | XLARGE_8C16G
timeoutMinutes: number # Job timeout in minutes. Default: 240. Range: 1–1440.
debugPolicy: string # onFailure | always. Retain environment for debugging.
debugRetentionMinutes: number # Debug retention period. Range: 1–240.
needs: string | [string] # Job dependencies within or across stages.
driven: string # Trigger method: auto (default) | manual.
condition: string # Conditional execution expression.
sourceOption: [string] # Source code download control.
steps: # Step-based job definition.
<step_id>: ...
component: string # Component-based job definition.
with: # Component runtime parameters.
key: value
plugins: # Notification plugins (DingTalk, email, WeCom, Lark, webhooks).
...Property summary
| Property | Required | Type | Description |
|---|---|---|---|
<job_id> | Yes | string | Unique job identifier. Letters, numbers, and underscores only. Must start with a letter. Max 64 characters. |
name | No | string | Display name. Defaults to the job_id value. Max 64 characters. |
runsOn | No | object | string | Build environment. Defaults to the Apsara DevOps Singapore public cluster (public/ap-southeast-1). |
runsOn.instanceType | No | string | Resource specification. Auto-allocated by default. |
timeoutMinutes | No | number | Job timeout. Default: 240 minutes. Range: 1–1,440 minutes. |
debugPolicy | No | string | Retain the build environment for debugging after completion. Requires debugRetentionMinutes. |
debugRetentionMinutes | No | number | Debug environment retention period in minutes. Range: 1–240. Requires debugPolicy. |
needs | No | string | list | Define dependencies between jobs. Supports cross-stage references. |
driven | No | string | Trigger method. Default: auto. |
condition | No | string | Expression that controls whether the job runs. |
sourceOption | No | list | Control which source code repositories to download. |
steps | No | object | Define the job as a sequence of steps sharing a workspace. |
component | No | string | Define the job as a component call. |
with | No | object | Runtime parameters passed to a component. |
plugins | No | object | Notification configuration for DingTalk, email, WeCom, Lark, or webhooks. |
Examples
Minimal step-based job
stages:
build_stage:
name: Build stage
jobs:
build_job:
name: Build task
runsOn: public/ap-southeast-1
steps:
build_step:
step: JavaBuild
name: Java build
with:
...Multiple steps in a container environment
stages:
build_stage:
name: Build stage
jobs:
build_job:
name: Build task
runsOn:
group: public/ap-southeast-1
container: build-steps-public-registry.ap-southeast-1.cr.aliyuncs.com/build-steps/alinux3:latest
steps:
setup_java_step:
name: "Set up Java environment"
step: SetupJava
with:
jdkVersion: "1.8"
mavenVersion: "3.5.2"
command_step:
name: "Run command"
step: Command
with:
run: |
mvn -B clean package -Dmaven.test.skip=true -Dautoconfig.skip
upload_artifact_step:
name: "Upload build output"
step: ArtifactUpload
with:
uploadType: flowPublic
artifact: "Artifacts_${PIPELINE_ID}"
filePath:
- target/Component-based job
Component-based jobs support retries and skips.
stages:
build_stage:
name: Build stage
jobs:
deploy_job:
name: Host group deployment task
component: VMDeploy
with:
artifact: $[stages.build_stage.build_job.upload_artifact_step.artifacts.default]
...Fan-out dependencies
One job triggers multiple downstream jobs:
jobs:
test_job:
name: Test job
build_job:
name: Build job
needs: test_job
deploy_job:
name: Deploy job
needs: test_jobFan-in dependencies
Multiple jobs converge into a single downstream job:
jobs:
unit_test:
name: Unit tests
integration_test:
name: Integration tests
deploy_job:
name: Deploy
needs:
- unit_test
- integration_testConditional execution based on job status
jobs:
job_1:
name: Job 1
job_2:
name: Job 2
job_3:
name: Job 3
needs:
- job_1
- job_2
condition: succeed(job_1) || succeed(job_2) # Runs if either Job 1 or Job 2 succeeds.Property reference
runsOn
The build environment for the job. Two environment types are supported:
Specified container environment -- Starts a container on the build machine and runs all steps inside it.
Default VM environment -- Runs steps directly on the host or VM.
If runsOn is not specified, the job runs on the Apsara DevOps Singapore public cluster (public/ap-southeast-1) by default.
runsOn accepts either a string shorthand or an object with detailed options:
String shorthand:
runsOn: public/ap-southeast-1Object form: Use when specifying a container, labels, VM mode, or instance type.
Specified container environment
Starts a specified container on the build machine. Currently supports only Apsara DevOps public build clusters.
jobs:
my_job:
name: My task
runsOn:
group: public/ap-southeast-1
container: build-steps-public-registry.ap-southeast-1.cr.aliyuncs.com/build-steps/alinux3:latestThe container value must be a public image address accessible from the internet. For official Apsara DevOps system images, see the system images repository.
Default VM environment
Runs steps directly on the host or VM. Only private build clusters support this mode.
jobs:
my_job:
name: My task
runsOn:
group: private/<private_build_cluster_ID>
labels: windows, amd64
vm: trueSet vm: true to enable the VM build environment. Use labels to target a specific operating system and architecture. Without labels, the task is randomly scheduled to a machine in the cluster.
Build clusters
| Build cluster | YAML identifier | Description |
|---|---|---|
| Apsara DevOps Singapore build cluster | group: public/ap-southeast-1 | Default public Kubernetes (K8s) cluster. Used when runsOn is not specified. |
| Private build cluster | group: private/<private_build_cluster_ID> | A private host cluster added to the enterprise. |
Private build cluster: supported operating systems and architectures
Private build clusters support Linux, Windows, and macOS machines. The following table lists the supported architectures and build environments.
| Operating system | Architecture | labels value | Supported environments |
|---|---|---|---|
| Linux | amd64 | linux,amd64 | Default environment, Default VM environment |
| Linux | arm64 | linux,arm64 | Default VM environment only. Set vm: true. |
| Windows | amd64 | windows,amd64 | Default VM environment only. Set vm: true. |
| Windows | arm64 | windows,arm64 | Default VM environment only. Set vm: true. |
| macOS | amd64 | darwin,amd64 | Default VM environment only. Set vm: true. |
| macOS | arm64 | darwin,arm64 | Default VM environment only. Set vm: true. |
runsOn.instanceType
The resource specification for the build environment. Apsara DevOps auto-allocates the DEFAULT specification based on the steps configured in the job. For more information about default specifications, see the build environment documentation.
Valid values: SMALL_1C2G, MEDIUM_2C4G, LARGE_4C8G, XLARGE_8C16G.
jobs:
my_job:
name: My task
runsOn:
group: public/ap-southeast-1
container: build-steps-public-registry.ap-southeast-1.cr.aliyuncs.com/build-steps/alinux3:latest
instanceType: LARGE_4C8GtimeoutMinutes
The maximum duration for the job in minutes. Default: 240 minutes. Range: 1–1,440 minutes.
jobs:
my_job:
name: My task
runsOn:
group: public/ap-southeast-1
container: build-steps-public-registry.ap-southeast-1.cr.aliyuncs.com/build-steps/alinux3:latest
timeoutMinutes: 60debugPolicy and debugRetentionMinutes
Retain the job execution environment after completion so you can log in and debug. These properties work only with the specified container environment.
Specify both properties or neither.
debugPolicy values:
| Value | Behavior |
|---|---|
onFailure | Retain the environment only when the job fails. Not retained for redline check failures. |
always | Retain the environment regardless of outcome. |
debugRetentionMinutes: An integer from 1 to 240 specifying how long to keep the environment.
jobs:
my_job:
name: My task
runsOn:
group: public/ap-southeast-1
container: build-steps-public-registry.ap-southeast-1.cr.aliyuncs.com/build-steps/alinux3:latest
debugPolicy: always
debugRetentionMinutes: 5needs
Define dependencies between jobs. By default, all jobs in a stage run in parallel. Use needs to enforce execution order.
Supported values:
A single job ID:
needs: test_jobA list of job IDs:
needs: - job_1 - job_2
Additional details:
Supports dependencies across different stages.
Avoid circular dependencies. For example, do not create a chain where Job A depends on Job B, Job B depends on Job C, and Job C depends on Job A.
jobs:
test_job:
name: Test job
build_job:
name: Build job
needs: test_jobdriven
The trigger method for the job. Default: auto.
| Value | Behavior |
|---|---|
auto | The job runs automatically. |
manual | The job requires manual confirmation before running. |
jobs:
my_job:
name: My task
runsOn:
group: public/ap-southeast-1
container: build-steps-public-registry.ap-southeast-1.cr.aliyuncs.com/build-steps/alinux3:latest
driven: manualcondition
Control whether a job runs by specifying a function expression. By default, a job runs only after all its preceding dependent jobs succeed.
Operators
Relational and logical operators are supported in condition expressions.
| Operator | Description | Example |
|---|---|---|
== | Equal to | "${CI_COMMIT_REF_NAME}" == "master" |
!= | Not equal to | "${CI_COMMIT_REF_NAME}" != "master" |
&& | And | "${CI_COMMIT_REF_NAME}" == "master" && succeed() |
|| | Or | "${CI_COMMIT_REF_NAME}" == "master" || "${CI_COMMIT_REF_NAME}" == "develop" |
! | Not | succeed('job1') && !skipped('job1') |
() | Grouping | ("${CI_COMMIT_REF_NAME}" == "master" || "${CI_COMMIT_REF_NAME}" == "develop") && succeed() |
Built-in functions
| Function | Description | Example |
|---|---|---|
startsWith(searchString, searchValue) | Returns true if searchString starts with searchValue. | condition: startsWith('Hello world','He') |
endsWith(searchString, searchValue) | Returns true if searchString ends with searchValue. | condition: endsWith('Hello world','ld') |
contains(search, item) | Returns true if search (an array) contains item. | condition: contains('["aa", "bb", "cc"]', 'aa') |
weekDay() | Returns the current day of the week (Monday through Sunday). | condition: weekDay()=="Thursday" |
timeIn(startTime, endTime) | Returns true if the current time falls between startTime and endTime. | condition: timeIn("20:00:00", "22:00:00") |
Function parameters can reference pipeline variables using${}. For example, if you set a pipeline variableTEST_VAR=["aa", "bb", "cc"], reference it in a function as follows:
jobs:
job_1:
name: 1
condition: contains('${TEST_VAR}', 'aa')Job status functions
Use these functions to check the execution status of preceding dependent jobs. Pass the <job_id> of a preceding job as the input parameter.
| Function | Description | Example |
|---|---|---|
always() | Always returns true. | condition: always() |
succeed() | Returns true if all specified preceding jobs have a status of Successful or Skipped. | condition: succeed('job_id_1','job_id_2') |
failed() | Returns true if at least one specified preceding job has a status of Failed or Canceled. | condition: failed('job_id_1','job_id_2') |
skipped() | Returns true if at least one specified preceding job has a status of Skipped. | condition: skipped('job_id_1','job_id_2') |
Without an input parameter, each function applies to all preceding dependent jobs. For example,succeed()returnstrueonly when every preceding job succeeds. The input parameter must be the<job_id>of a job with a declared dependency. Specifying a<job_id>without a dependency relationship produces unexpected results.
Example -- run a job based on preceding job status:
jobs:
job_1:
name: Job 1
job_2:
name: Job 2
job_3:
name: Job 3
needs:
- job_1
- job_2
condition: succeed(job_1) || succeed(job_2) # Runs if either Job 1 or Job 2 succeeds.sourceOption
Control which pipeline source code repositories are downloaded before the job runs. By default, all configured pipeline source files are downloaded.
| Scenario | Configuration | Example |
|---|---|---|
| Download all source files | Do not specify sourceOption. | (not specified) |
| Download no source files | Specify an empty list. | sourceOption: [] |
| Download specific source files | List the <source_id> values. | sourceOption: [repo_1, repo_2] |
steps
Define the job as a sequence of steps. Steps share a workspace and run in order.
For more information, see Pipeline steps.
component
Define the job as a single component call. Component-based jobs support retries and skips.
For more information, see Pipeline components.
with
Specify runtime parameters for a component-based job. Use with together with component.
jobs:
deploy_job:
name: Host group deployment task
component: VMDeploy
with:
artifact: $[stages.build_stage.build_job.upload_step.artifacts.default]
machineGroup: <YOUR-MACHINE-GROUP-ID>
...For more information, see Pipeline components.
plugins
Configure notification channels for job-level events. Supported channels: DingTalk, email, WeCom, Lark, and webhooks.
For more information, see Pipeline plugins.