CNB

Stage

# Stage Introduction

  • type: Job | Array<Job> | Object<name: Job>

Stage represents a build stage that can consist of one or more Jobs. See Job Introduction for more information.

# Single Job

If a Stage has only one Job, the Stage can be omitted, and the Job can be written directly.

stages:
  - name: stage1
    jobs:
      - name: job A
        script: echo hello

It can be simplified as follows:

- stages:
    - name: job A
      script: echo hello

# Serial Jobs

When the value is an array (ordered), the group of Jobs will be executed serially.

# Serial Jobs
stages:
  - name: install
    jobs:
      - name: job1
        script: echo "job1"
      - name: job2
        script: echo "job2"

# Parallel Jobs

When the value is an object (unordered), the group of Jobs will be executed in parallel.

# Parallel Jobs
stages:
  - name: install
    jobs:
      job1:
        script: echo "job1"
      job2:
        script: echo "job2"

Multiple Jobs can be organized flexibly in serial or parallel. Here's an example of first serial, then parallel execution:

main:
  push:
    - stages:
        - name: serial first
          script: echo "serial"
        - name: parallel
          jobs:
            parallel job 1:
              script: echo "1"
            parallel job 2:
              script: echo "2"
        - name: serial next
          script: echo "serial next"

# name

  • type: String

The name of the Stage.

# ifNewBranch

  • type: Boolean
  • default: false

If set to true, the Stage will only be executed when the current branch is a new branch (i.e., CNB_IS_NEW_BRANCH is true).

If any of the conditions ifNewBranch / ifModify / if are satisfied simultaneously, the Stage will be executed.

# ifModify

  • type: Array<String> | String

Specifies that the Stage should only be executed when the corresponding files have changed. It can be a glob matching string or an array of glob matching strings.

# if

  • type: Array<String> | String

One or more Shell scripts that determine whether the Stage should be executed based on the exit code of the script. When the exit code is 0, it indicates that the step should be executed.

Example 1: Checking the value of a variable

Shell expression syntax (opens new window)

main:
  push:
    - env:
        IS_NEW: true
      stages:
        - name: is new
          if: |
            [ "$IS_NEW" = "true" ]
          script: echo is new
        - name: is not new
          if: |
            [ "$IS_NEW" != "true" ]
          script: echo not new

Example 2: Checking the output of a task

main:
  push:
    - stages:
        - name: make info
          script: echo 'haha'
          exports:
            info: RESULT
        - name: run if RESULT is haha
          if: |
            [ "$RESULT" = "haha" ]
          script: echo $RESULT

# env

  • type: Object

Same as Pipeline env, but only applicable to the current Stage.

Stage env takes precedence over Pipeline env.

# imports

  • type: Array<String> | String

Same as Pipeline imports, but only applicable to the current Stage.

# retry

  • type: Number
  • default: 0

Number of retry attempts in case of failure. 0 means no retries.

# lock

  • type: Boolean | Object

Sets a lock for the Stage. The lock is automatically released after the Stage is executed. Locks cannot be used across repositories.

Behavior: If task A acquires the lock, task B will wait for the lock to be released before it can acquire the lock and continue executing the task.

  • lock.key

    • type: String

    Custom lock name. The default value is branchName-pipelineName-stageIndex.

  • lock.expires

    • type: Number
    • default: 3600 (1 hour)

    Lock expiration time in seconds. After expiration, the lock is automatically released.

  • lock.wait

    • type: Boolean
    • default: false

    Specifies whether to wait if the lock is already occupied.

  • lock.timeout

    • type: Number
    • default: 3600 (1 hour)

    Specifies the timeout for waiting for the lock in seconds.

Example 1: lock in Boolean format

main:
  push:
    - stages:
        - name: stage1
          lock: true
          jobs:
            - name: job1
              script: echo "job1"

Example 2: lock in Object format

main:
  push:
    - stages:
        - name: stage1
          lock:
            key: key
            expires: 600 # 10 minutes
            wait: true
            timeout: 60 # maximum wait time of 1 minute
          jobs:
            - name: job1
              script: echo "job1"

# image

  • type: Object | String

Specifies the environment image for the current Stage. All tasks under this Stage will be executed in this image environment by default.

  • image.name:

    • type: String

    The name of the image, such as node:14.

  • image.dockerUser:

    • type: String

    Specifies the Docker username for pulling the specified image. This is required if the specified image is private. Otherwise, there may be permission issues when pulling the image.

  • image.dockerPassword:

    • type: String

    Specifies the Docker user password for pulling the specified image. This is required if the specified image is private. Otherwise, there may be permission issues when pulling the image.

If image is specified as a string, it is equivalent to specifying image.name.

← Job →