All Products
Search
Document Center

Alibaba Cloud DevOps:Pipeline jobs

Last Updated:Mar 01, 2026

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

PropertyRequiredTypeDescription
<job_id>YesstringUnique job identifier. Letters, numbers, and underscores only. Must start with a letter. Max 64 characters.
nameNostringDisplay name. Defaults to the job_id value. Max 64 characters.
runsOnNoobject | stringBuild environment. Defaults to the Apsara DevOps Singapore public cluster (public/ap-southeast-1).
runsOn.instanceTypeNostringResource specification. Auto-allocated by default.
timeoutMinutesNonumberJob timeout. Default: 240 minutes. Range: 1–1,440 minutes.
debugPolicyNostringRetain the build environment for debugging after completion. Requires debugRetentionMinutes.
debugRetentionMinutesNonumberDebug environment retention period in minutes. Range: 1–240. Requires debugPolicy.
needsNostring | listDefine dependencies between jobs. Supports cross-stage references.
drivenNostringTrigger method. Default: auto.
conditionNostringExpression that controls whether the job runs.
sourceOptionNolistControl which source code repositories to download.
stepsNoobjectDefine the job as a sequence of steps sharing a workspace.
componentNostringDefine the job as a component call.
withNoobjectRuntime parameters passed to a component.
pluginsNoobjectNotification 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_job

Fan-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_test

Conditional 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-1

  • Object 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:latest

The 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: true

Set 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 clusterYAML identifierDescription
Apsara DevOps Singapore build clustergroup: public/ap-southeast-1Default public Kubernetes (K8s) cluster. Used when runsOn is not specified.
Private build clustergroup: 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 systemArchitecturelabels valueSupported environments
Linuxamd64linux,amd64Default environment, Default VM environment
Linuxarm64linux,arm64Default VM environment only. Set vm: true.
Windowsamd64windows,amd64Default VM environment only. Set vm: true.
Windowsarm64windows,arm64Default VM environment only. Set vm: true.
macOSamd64darwin,amd64Default VM environment only. Set vm: true.
macOSarm64darwin,arm64Default 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_4C8G

timeoutMinutes

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: 60

debugPolicy 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:

ValueBehavior
onFailureRetain the environment only when the job fails. Not retained for redline check failures.
alwaysRetain 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: 5

needs

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_job

  • A 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_job

driven

The trigger method for the job. Default: auto.

ValueBehavior
autoThe job runs automatically.
manualThe 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: manual

condition

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.

OperatorDescriptionExample
==Equal to"${CI_COMMIT_REF_NAME}" == "master"
!=Not equal to"${CI_COMMIT_REF_NAME}" != "master"
&&And"${CI_COMMIT_REF_NAME}" == "master" && succeed()
&#124;&#124;Or"${CI_COMMIT_REF_NAME}" == "master" &#124;&#124; "${CI_COMMIT_REF_NAME}" == "develop"
!Notsucceed('job1') && !skipped('job1')
()Grouping("${CI_COMMIT_REF_NAME}" == "master" &#124;&#124; "${CI_COMMIT_REF_NAME}" == "develop") && succeed()

Built-in functions

FunctionDescriptionExample
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 variable TEST_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.

FunctionDescriptionExample
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() returns true only 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.

ScenarioConfigurationExample
Download all source filesDo not specify sourceOption.(not specified)
Download no source filesSpecify an empty list.sourceOption: []
Download specific source filesList 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.

See also