CNB

Environment Variables

Environment variables that can be used during the build process.

# Default Environment Variables

Default environment variables are read-only and cannot be overwritten during the build process.

The section on "Merge-related events" includes the following six types:

  • pull_request
  • pull_request.target
  • pull_request.approved
  • pull_request.changes_requested
  • pull_request.mergeable
  • pull_request.merged

For more information, please refer to the Branch Events documentation.

# CI

true

# CNB

true

# CNB_WEB_PROTOCOL

The protocol currently used by the web, http | https

# CNB_WEB_HOST

The HOST currently used by the web

# CNB_WEB_ENDPOINT

The address currently used by the web, including the protocol, HOST, and path (if any)

# CNB_API_ENDPOINT

The current API address, including the protocol, HOST, and path (if any)

Can be used in CI to call API interfaces in conjunction with CNB_TOKEN

# CNB_GROUP_SLUG

Repository's organization path.

# CNB_GROUP_SLUG_LOWERCASE

Repository's organization path (in lowercase format)

# CNB_EVENT

The value is the name of the event that triggered the build

Event types can be found in the Events documentation

# CNB_EVENT_URL

  • For builds triggered by "Merge-related events" the value is the link to the corresponding PR
  • For builds triggered by "push," "branch.create," or "tag_push" events, the value is the link to the latest commit
  • Otherwise, the value is an empty string

# CNB_BRANCH

  • For builds triggered by "push," "branch.create," or "branch.delete" events, the value is the current branch name
  • For builds triggered by "Merge-related events" the value is the branch name of the target branch
  • For builds triggered by "tag_push" events, the value is the name of the tag
  • For builds triggered by "custom events," the value is the corresponding branch name
  • For builds triggered by a "crontab," the value is the corresponding branch name

# CNB_BRANCH_SHA

  • For builds triggered by "branch.delete," the value is an empty string
  • For other cases, the value of CNB_BRANCH is the SHA of the most recent commit

# CNB_TOKEN_USER_NAME

The username corresponding to a temporary token for users is fixed as "cnb"

# CNB_TOKEN

User token, which can be used for code submission, API calls, etc.

For pull_request events, the permissions are:

  • repo-code:r
  • repo-pr:r
  • repo-issue:r
  • repo-notes:rw
  • repo-contents:r
  • repo-registry:r
  • repo-commit-status:rw
  • account-profile:r

For non-pull_request events, the permissions are:

  • repo-code:rw
  • repo-pr:rw
  • repo-issue:rw
  • repo-notes:rw
  • repo-contents:rw
  • repo-registry:rw
  • repo-commit-status:rw
  • repo-cnb-trigger:rw
  • repo-cnb-history:r
  • repo-cnb-detail:r
  • repo-basic-info:r
  • repo-manage:r
  • account-profile:r
  • group-resource:r

For the meaning of permissions, refer to the Access Token in the Personal Settings page.

# CNB_IS_CRONEVENT

Is it a crontab task

# CNB_DOCKER_REGISTRY

Artifact repository Docker source address

# CNB_HELM_REGISTRY

Artifact repository Helm source address

# CNB_BEFORE_SHA

For builds triggered by push, the value is the sha of the most recent commit before the push. For push caused by branch.create, the value is '0000000000000000000000000000000000000000'

# CNB_COMMIT

  • For builds triggered by push or branch.create, it is the sha of the last commit
  • For builds triggered by branch.delete, it is the sha of the last commit on the main branch
  • For builds triggered by pull_request or pull_request.mergeable, it is the sha of the last commit on the source branch
  • For builds triggered by pull_request.target or pull_request.merged, it is the sha of the last commit on the target branch
  • For builds triggered by tag_push, it is the sha of the last commit associated with that specific tag
  • For builds triggered by custom events or scheduled events, it is the sha of the last commit on the specified branch

# CNB_COMMIT_SHORT

The abbreviation for CNB_COMMIT is the first 8 characters of it

# CNB_COMMIT_MESSAGE

The commit information corresponding to CNB_COMMIT

# CNB_COMMIT_MESSAGE_TITLE

The title part of CNB_COMMIT_MESSAGE refers to the first line

# CNB_COMMITTER

The committer corresponding to CNB_COMMIT

# CNB_COMMITTER_EMAIL

The email address corresponding to CNB_COMMITTER

# CNB_IS_TAG

For builds with a tag, the value is true

# CNB_TAG_MESSAGE

  • Tag Message: For builds with a tag, this environment variable will be present
  • Otherwise, the value is an empty string

# CNB_TAG_RELEASE_TITLE

  • Release Title: For builds with a tag, the value is only present if the release title is not empty
  • Otherwise, the value is an empty string

# CNB_TAG_RELEASE_DESC

  • Release Description: For builds with a tag, the value is only present if the release description is not empty
  • Otherwise, the value is an empty string

# CNB_TAG_IS_RELEASE

  • Tag has corresponding Release: For builds with a tag, if the tag has a corresponding release, the value is true
  • Otherwise, the value is false.

# CNB_TAG_IS_PRE_RELEASE

  • For builds with a tag, if there is a corresponding release and the release is a "pre-release," then the value is true
  • Otherwise, the value is false.

# CNB_REPO_SLUG

The target repository path should be in the format group_slug/repo_name.

# CNB_REPO_SLUG_LOWERCASE

The lowercase format for the target repository path

# CNB_REPO_NAME

target repository name

# CNB_REPO_ID

the id of the target repository

# CNB_REPO_URL_HTTPS

HTTPS address of the target repository

# CNB_BUILD_ID

The current build number, globally unique

# CNB_BUILD_WEB_URL

The log address of the current build

# CNB_BUILD_START_TIME

The start time of the current build in UTC format is Tue Oct 19 2021 17:09:14 GMT+0800

# CNB_BUILD_USER

The name of the triggerer for the current build

# CNB_BUILD_USER_ID

The ID of the triggerer for the current build

# CNB_BUILD_STAGE_NAME

The name of the current build stage

# CNB_BUILD_JOB_NAME

The name of the current build job

# CNB_BUILD_JOB_KEY

The unique key of the current build job within the same stage

# CNB_BUILD_WORKSPACE

The root directory of the workspace where the custom shell script is executed

# CNB_BUILD_FAILED_MSG

The error message for the failed pipeline build, which can be used in the failStages section

# CNB_BUILD_FAILED_STAGE_NAME

The name of the failed stage in the pipeline build, which can be used in the failStages section

# CNB_PIPELINE_NAME

当前 pipeline 的 name，没声明时为空

# CNB_PIPELINE_KEY

The index key of the current pipeline, for example, pipeline-0

# CNB_PIPELINE_ID

The unique ID of the current pipeline, which is a globally unique string

# CNB_PIPELINE_DOCKER_IMAGE

The Docker image being used by the current pipeline, for example, alpine:latest

# CNB_PIPELINE_ENDPOINT_*

The endpoints corresponding to the current pipeline, for example: CNB_PIPELINE_ENDPOINT_80 = ip:port

# CNB_RUNNER_IP

The IP address of the Runner where the current pipeline is running

# CNB_CPUS

The maximum number of CPU cores that can be used by the current pipeline during the build process

# CNB_PULL_REQUEST

  • For builds triggered by a pull_request or pull_request.target, the value would be true
  • Otherwise, the value would be false

# CNB_PULL_REQUEST_LIKE

  • For builds triggered by "Merge-related events" the value would be true
  • Otherwise, the value would be false

# CNB_PULL_REQUEST_PROPOSER

  • For builds triggered by "Merge-related events" the value would be the name of the person who raised the PR
  • Otherwise, the value would be an empty string

# CNB_PULL_REQUEST_TITLE

  • For builds triggered by "Merge-related events" the value would be the title filled in when raising the PR
  • Otherwise, the value would be an empty string

# CNB_PULL_REQUEST_DESC

  • For builds triggered by "Merge-related events" the value would be the description filled in when raising the PR
  • Otherwise, the value would be an empty string

# CNB_PULL_REQUEST_BRANCH

  • For builds triggered by "Merge-related events" the value would be the source branch name of the initiated PR
  • Otherwise, the value would be an empty string

# CNB_PULL_REQUEST_SHA

  • For builds triggered by "Merge-related events" the value would be the latest commit SHA of the current PR source branch
  • Otherwise, the value would be an empty string

# CNB_PULL_REQUEST_TARGET_SHA

  • For builds triggered by "Merge-related events" the value would be the latest commit SHA of the current PR target branch
  • Otherwise, the value would be an empty string

# CNB_PULL_REQUEST_MERGE_SHA

  • For builds triggered by the pull_request.merged event, the value would be the SHA of the commit after the current PR is merged
  • 对于由 pull_request、pull_request.target、pull_request.mergeable 触发的构建，值将是当前 PR 预合并后的 SHA。
  • Otherwise, the value would be an empty string

# CNB_PULL_REQUEST_SLUG

  • For builds triggered by "Merge-related events" the value will be the repository slug of the source repository, such as group_name/repo_name
  • Otherwise, the value would be an empty string

# CNB_PULL_REQUEST_ACTION

For builds triggered by "Merge-related events", the possible values are:

  • created: New pull request (PR)
  • code_update: Source branch push
  • status_update: When the review is approved or the CI status changes, the PR becomes mergeable Otherwise, the value would be an empty string

# CNB_PULL_REQUEST_ID

  • For builds triggered by "Merge-related events", the value will be the globally unique id of the current or associated PR
  • Otherwise, the value would be an empty string

# CNB_PULL_REQUEST_IID

  • For builds triggered by "Merge-related events", the value will be the iid (internal ID) of the current or associated PR in the repository
  • Otherwise, the value would be an empty string

# CNB_PULL_REQUEST_REVIEWERS

  • For builds triggered by "Merge-related events," the value will be a list of reviewers separated by commas (,)
  • Otherwise, the value would be an empty string

# CNB_PULL_REQUEST_REVIEW_STATE

For builds triggered by "Merge-related events"

  • If there are reviewers and someone has approved the review, the value is "approve"
  • If there are reviewers but no one has approved the review, the value is "unapprove"
  • Otherwise, the value would be an empty string

# CNB_REVIEW_REVIEWED_BY

  • For builds triggered by "Merge-related events," the value will be a list of reviewers who have approved the review, separated by commas (,)
  • Otherwise, the value would be an empty string

# CNB_REVIEW_LAST_REVIEWED_BY

  • For builds triggered by "Merge-related events," the value will be the last reviewer who approved the review
  • Otherwise, the value would be an empty string

# CNB_IS_NEW_BRANCH

Is the current branch a newly created branch, with a default value of false

# CNB_IS_NEW_BRANCH_WITH_UPDATE

Is the current branch a newly created branch with new commits, with a default value of false

# CNB_IS_RETRY

Is the current build triggered by a rebuild command?

# HUSKY_SKIP_INSTALL

Making Husky compatible with a CI environment

# CNB_VSCODE_WEB_URL

The remote development address for VSCode is only available when the services field is declared as vscode

# CNB_ISSUE_ID

  • For builds triggered by issue.*, the value is the globally unique ID of the issue
  • Otherwise, the value would be an empty string

# CNB_ISSUE_IID

  • For builds triggered by issue.*, the value is the iid (internal ID) of the issue in the repository.
  • Otherwise, the value would be an empty string

# CNB_ISSUE_TITLE

  • For builds triggered by issue.*, the value is the title of the issue
  • Otherwise, the value would be an empty string

# CNB_ISSUE_DESCRIPTION

  • For builds triggered by issue.*, the value is the description of the issue
  • Otherwise, the value would be an empty string

# CNB_ISSUE_OWNER

  • For builds triggered by issue.*, the value is the username of the author of the issue.
  • Otherwise, the value would be an empty string

# CNB_ISSUE_STATE

  • For builds triggered by issue.*, the value is the status of the issue: open or closed.
  • Otherwise, the value would be an empty string

# Using Environment Variables

In addition to using environment variables in shell scripts, they can also be used in the options property of built-in tasks.

# Using in script

main:
  push:
    - stages:
        - name: test internal env
          script: echo $CNB_BRANCH

# Using in options of built-in tasks

main:
  push:
    - env:
        COMMIT_MSG: commit message
        ADD_PATH: release/
      stages:
        - name: xxxx
          type: xxx:xxx
          options:
            commitMessage: ${COMMIT_MSG}
            mergeType: rebase
            keepCommit: false
            add: ${ADD_PATH}

# Preventing Environment Variable Substitution

By default, fields in the options section undergo environment variable substitution during task execution.

For example:

options:
  shell: |
    echo '$CNB_EVENT'
    echo '$myVar'

After substitution:

options:
  shell: |
    echo 'push'
    echo ''

If you don't want myVar to be substituted, you can use \$ to prevent substitution:

options:
  shell: |
    echo '$CNB_EVENT'
    echo '\$myVar'

After substitution:

options:
  shell: |
    echo 'push'
    echo '$myVar'

# Declaring Environment Variables

  1. Declare environment variables using env.
  2. Environment variables declared in the Pipeline are valid for the current Pipeline.
  3. Environment variables declared in the Job are valid for the current Job.
main:
  push:
    - env:
        COMMIT_MSG: commit message
      stages:
        - name: xxxx
          type: xxx:xxx
          env:
            ADD_PATH: release/
          options:
            commitMessage: ${COMMIT_MSG}
            mergeType: rebase
            keepCommit: false
            add: ${ADD_PATH}

# Importing Environment Variables

  1. Use imports to refer to a file in a private Git repository, allowing you to inject private credentials into environment variables.
  2. When there is a conflict between env and imports keys, env takes precedence.
main:
  push:
    - services:
        - docker
      imports: https://xxx/envs.yml
      stages:
        - name: docker info
          script: docker info
        - name: docker login
          script: docker login ${imageDomain} -u $TEST_DOCKER_USER -p $TEST_DOCKER_PWD

Example content of https://xxx/envs.yml:

TEST_DOCKER_USER: your_docker_username
TEST_DOCKER_PWD: your_docker_password
TEST_NPM_USER: your_npm_username
TEST_NPM_PWD: your_npm_password

whatever_key_you_want: whatever_value_you_want

# Modifying Environment Variables

You can modify, add, or delete environment variables within a Job using the exports property, which has a lifecycle limited to the current Pipeline.

exports:
  from-key: to-key
  • exports is an object where the object's key is the key of the output object for this Job, and the value is the mapped environment variable name.
    • from-key specifies the original key to be transformed, supports environment variables, and supports deep value retrieval.
    • to-key specifies the transformed key.

# Exporting Environment Variables from Job Return Values

For custom script tasks, the following properties can be set:

  • code: Exit code

  • stdout: Standard output

  • stderr: Standard error

  • info: Combined output of standard output and standard error in chronological order

    TIP

    Note: It is recommended to use printf "%s" "hello\nworld" to output variables to eliminate the trailing newline character in the standard output stream while preserving escape characters such as \n.

For tasks that include conditional logic such as if, ifModify, ifNewBranch, the following property can be set:

  • skip: If not skipped, returns an empty string; if skipped, returns the reason for skipping (if, ifModify, ifNewBranch).
- name: use if
  if: exit -1
  exports:
    skip: REASON
- name: tell last
  script: echo $REASON # The value of $REASON is the string "if"

# Modifying, Adding, and Deleting Environment Variables

main:
  push:
    - env:
        CUSTOM_ENV_DATE_INFO: default
        CUSTOM_ENV_FOR_DELETE: default
      stages:
        - name: set env
          script: echo -n $(date "+%Y-%m-%d %H:%M")
          exports:
            # Adding
            code: CUSTOM_ENV_DATE_CODE
            # Modifying
            info: CUSTOM_ENV_DATE_INFO
            # Deleting
            CUSTOM_ENV_FOR_DELETE: null
            # Deleting
            # CUSTOM_ENV_FOR_DELETE:
        - name: tag
          type: xxx:xxxx
          exports:
            # Supports deep value retrieval
            nextRelease.gitTag: CUSTOM_ENV_GIT_TAG
        - name: echo env
          script:
            - echo $CUSTOM_ENV_DATE_CODE
            - echo $CUSTOM_ENV_DATE_INFO
            - echo $CUSTOM_ENV_DATE_STDOUT
            - echo $CUSTOM_ENV_FOR_DELETE
            - echo $CUSTOM_ENV_GIT_TAG

# Modifying Environment Variables in Built-in Tasks

main:
  push:
    - stages:
        - name: xxxx
          type: xxx:xxx
          options:
            product: public
            name: cnb
            dist: release/
          exports:
            version: CUSTOM_ENV_VERSION
            url: CUSTOM_ENV_URL
        - name: echo env
          script:
            - echo $CUSTOM_ENV_VERSION
            - echo $CUSTOM_ENV_URL