环境变量
在构建过程中可以使用的环境变量。
# 默认环境变量
默认环境变量只可读不可写,如果构建过程中尝试覆盖默认环境变量将不会生效。
下文 合并类事件
包含以下六种:
pull_request
pull_request.target
pull_request.approved
pull_request.changes_requested
pull_request.mergeable
pull_request.merged
了解更多分支事件。
- 基础变量
- 提交类变量
- 仓库类变量
- 构建类变量
- CNB_BUILD_ID
- CNB_BUILD_WEB_URL
- CNB_BUILD_START_TIME
- CNB_BUILD_USER
- CNB_BUILD_USER_ID
- CNB_BUILD_STAGE_NAME
- CNB_BUILD_JOB_NAME
- CNB_BUILD_JOB_KEY
- CNB_BUILD_WORKSPACE
- CNB_BUILD_FAILED_MSG
- CNB_BUILD_FAILED_STAGE_NAME
- CNB_PIPELINE_NAME
- CNB_PIPELINE_KEY
- CNB_PIPELINE_ID
- CNB_PIPELINE_DOCKER_IMAGE
- CNB_PIPELINE_ENDPOINT_*
- CNB_RUNNER_IP
- CNB_CPUS
- CNB_IS_RETRY
- 合并类变量
- CNB_PULL_REQUEST
- CNB_PULL_REQUEST_LIKE
- CNB_PULL_REQUEST_PROPOSER
- CNB_PULL_REQUEST_TITLE
- CNB_PULL_REQUEST_DESC
- CNB_PULL_REQUEST_BRANCH
- CNB_PULL_REQUEST_SHA
- CNB_PULL_REQUEST_TARGET_SHA
- CNB_PULL_REQUEST_MERGE_SHA
- CNB_PULL_REQUEST_SLUG
- CNB_PULL_REQUEST_ACTION
- CNB_PULL_REQUEST_ID
- CNB_PULL_REQUEST_IID
- CNB_PULL_REQUEST_REVIEWERS
- CNB_PULL_REQUEST_REVIEW_STATE
- CNB_REVIEW_REVIEWED_BY
- CNB_REVIEW_LAST_REVIEWED_BY
- 远程开发类变量
- Issue类变量
# CI
true
# CNB
true
# CNB_WEB_PROTOCOL
当前 web 使用的协议,http | https
# CNB_WEB_HOST
当前 web 使用的 HOST
# CNB_WEB_ENDPOINT
当前 web 使用的地址,包含协议、HOST、路径(如有)
# CNB_API_ENDPOINT
当前 API 地址,包含协议、HOST、路径(如有)
可与 CNB_TOKEN
配合在 CI 中调用 API 接口
# CNB_GROUP_SLUG
仓库所属组织路径
# CNB_GROUP_SLUG_LOWERCASE
仓库所属组织路径(小写格式)
# CNB_EVENT
值为触发构建的事件名称
事件类型参见事件
# CNB_EVENT_URL
- 对于由
合并类事件
触发的构建,值为该PR
的链接 - 对于由
push
、branch.create
、tag_push
触发的构建,值为最新Commit
的链接 - 否则值为空字符串
# CNB_BRANCH
- 对于由
push
、branch.create
、branch.delete
触发的构建,值为当前的分支名 - 对于由
合并类事件
触发的构建,值为目标分支的分支名 - 对于由
tag_push
触发的构建,值为tag
名 - 对于由
自定义事件
触发的构建,值为对应的分支名称 - 对于由
crontab
触发的构建,值为对应的分支名称
# CNB_BRANCH_SHA
- 对于
branch.delete
触发的构建,为空字符串 - 其他情况为
CNB_BRANCH
最近一次提交的sha
# CNB_TOKEN_USER_NAME
用户临时令牌对应的用户名,固定为 cnb
# CNB_TOKEN
用户令牌,可用于代码提交、API 调用等
对于 pull_request
事件,权限有:
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
对于非 pull_request
事件,权限有:
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
权限含义参考页面 个人设置
页面的 访问令牌
# CNB_IS_CRONEVENT
是否是定时任务事件
# CNB_DOCKER_REGISTRY
制品库 Docker 源地址
# CNB_HELM_REGISTRY
制品库 Helm 源地址
# CNB_BEFORE_SHA
对于由 push
触发的构建,值为 push 前最近一次提交的 sha
。对于 branch.create
引起的 push
,值为 '0000000000000000000000000000000000000000'
# CNB_COMMIT
- 对于
push
、branch.create
触发的构建,是最后一次提交的sha
- 对于
branch.delete
触发的构建,是主分支最后一次提交的sha
- 对于
pull_request
、pull_request.mergeable
触发的构建,是源分支最后一次提交的sha
- 对于
pull_request.target
、pull_request.merged
触发的构建,是目标分支最后一次提交的sha
- 对于
tag_push
触发的构建,是该 tag 最后一次提交的sha
- 对于
自定义事件
、定时器事件
触发的构建,是指定分支的最后一次提交的sha
# CNB_COMMIT_SHORT
CNB_COMMIT
的缩写,取其前 8 位字符
# CNB_COMMIT_MESSAGE
CNB_COMMIT
对应的提交信息
# CNB_COMMIT_MESSAGE_TITLE
CNB_COMMIT_MESSAGE
的 title
部分,即首行
# CNB_COMMITTER
CNB_COMMIT
对应的提交者
# CNB_COMMITTER_EMAIL
CNB_COMMITTER
对应的邮箱
# CNB_IS_TAG
对于分支为 Tag 的构建,值为 ture
# CNB_TAG_MESSAGE
Tag message
:对于分支为 Tag 的构建, 会有该环境变量- 否则值为空字符串
# CNB_TAG_RELEASE_TITLE
Release 标题
:对于分支为 Tag 的构建, 如果 release 标题不为空,才会有值- 否则值为空字符串
# CNB_TAG_RELEASE_DESC
Release 描述
:对于分支为 Tag 的构建, 且 release 描述不为空,才会有值- 否则值为空字符串
# CNB_TAG_IS_RELEASE
Tag 是否存在对应的 Release
:对于分支为 Tag 的构建,如果tag
存在对应的release
,则为true
- 否则为
false
# CNB_TAG_IS_PRE_RELEASE
- 对于分支为 Tag 的构建,若存在对应的
release
,且release
为预发布
,则值为true
- 否则为
false
# CNB_REPO_SLUG
目标仓库路径,格式为 group_slug/repo_name
# CNB_REPO_SLUG_LOWERCASE
目标仓库路径小写格式
# CNB_REPO_NAME
目标仓库名称
# CNB_REPO_ID
目标仓库的 id
# CNB_REPO_URL_HTTPS
目标仓库仓库 https 地址
# CNB_BUILD_ID
当前构建的流水号,全局唯一
# CNB_BUILD_WEB_URL
当前构建的日志地址
# CNB_BUILD_START_TIME
当前构建的开始时间,UTC格式,示例 Tue Oct 19 2021 17:09:14 GMT+0800
# CNB_BUILD_USER
当前构建的触发者名称
# CNB_BUILD_USER_ID
当前构建的触发者 id
# CNB_BUILD_STAGE_NAME
当前构建的 stage
名称
# CNB_BUILD_JOB_NAME
当前构建的 job
名称
# CNB_BUILD_JOB_KEY
当前构建的 job
key,同 stage
下唯一
# CNB_BUILD_WORKSPACE
自定义 shell
脚本执行的工作空间根目录
# CNB_BUILD_FAILED_MSG
流水线构建失败的错误信息,可在 failStages
中使用
# CNB_BUILD_FAILED_STAGE_NAME
流水线构建失败的 stage
的名称,可在 failStages
中使用
# CNB_PIPELINE_NAME
当前 pipeline
的 name
,没声明时为空
# CNB_PIPELINE_KEY
当前 pipeline
的索引 key
,例如 pipeline-0
# CNB_PIPELINE_ID
当前 pipeline
的 id
,全局唯一字符串
# CNB_PIPELINE_DOCKER_IMAGE
当前 pipeline
所使用的 docker image
,如:alpine:latest
# CNB_PIPELINE_ENDPOINT_*
当前 pipeline
对应的 endpoints
,如:CNB_PIPELINE_ENDPOINT_80
= ip:port
# CNB_RUNNER_IP
当前 pipeline
所在 Runner
的 ip
# CNB_CPUS
当前构建流水线可以使用的最大 cpu 核数
# CNB_PULL_REQUEST
- 对于由
pull_request
、pull_request.target
触发的构建,值为true
- 否则值为
false
# CNB_PULL_REQUEST_LIKE
- 对于由
合并类事件
触发的构建,值为true
- 否则值为
false
# CNB_PULL_REQUEST_PROPOSER
- 对于由
合并类事件
触发的构建,值为提出PR
者名称 - 否则值为空字符串
# CNB_PULL_REQUEST_TITLE
- 对于由
合并类事件
触发的构建,值为提PR
时候填写的标题 - 否则值为空字符串
# CNB_PULL_REQUEST_DESC
- 对于由
合并类事件
触发的构建,值为提PR
时候填写的描述 - 否则值为空字符串
# CNB_PULL_REQUEST_BRANCH
- 对于由
合并类事件
触发的构建,值为发起PR
的源分支名称 - 否则值为空字符串
# CNB_PULL_REQUEST_SHA
- 对于由
合并类事件
触发的构建,值为当前PR
源分支最新的提交sha
- 否则值为空字符串
# CNB_PULL_REQUEST_TARGET_SHA
- 对于由
合并类事件
触发的构建,值为当前PR
目标分支最新的提交sha
- 否则值为空字符串
# CNB_PULL_REQUEST_MERGE_SHA
- 对于由
pull_request.merged
事件触发的构建,值为当前PR
合并后的sha
- 对于由
pull_request
、pull_request.target
、pull_request.mergeable
触发的构建,值为当前PR
预合并后的sha
- 否则值为空字符串
# CNB_PULL_REQUEST_SLUG
- 对于由
合并类事件
触发的构建,值为源仓库的仓库slug
,如group_name/repo_name
- 否则值为空字符串
# CNB_PULL_REQUEST_ACTION
对于由 合并类事件
触发的构建,可能的值有:
created
: 新建PR
code_update
: 源分支 pushstatus_update
: 评审通过或 CI 状态变更时PR
变成可合并 否则值为空字符串
# CNB_PULL_REQUEST_ID
- 对于由
合并类事件
触发的构建,值为当前或者关联PR
的全局唯一id
- 否则值为空字符串
# CNB_PULL_REQUEST_IID
- 对于由
合并类事件
触发的构建,值为当前或者关联PR
在仓库中的编号iid
- 否则值为空字符串
# CNB_PULL_REQUEST_REVIEWERS
- 对于由
合并类事件
触发的构建,值为评审人列表,多个以,
分隔 - 否则值为空字符串
# CNB_PULL_REQUEST_REVIEW_STATE
对于由 合并类事件
触发的构建
- 有评审者且有人通过评审,值为approve
- 有评审者但无人通过评审,值为unapprove
- 否则值为空字符串
# CNB_REVIEW_REVIEWED_BY
- 对于由
合并类事件
触发的构建,值为同意评审的评审人列表,多个以,
分隔 - 否则值为空字符串
# CNB_REVIEW_LAST_REVIEWED_BY
- 对于由
合并类事件
触发的构建,值为最后一个同意评审的评审人 - 否则值为空字符串
# CNB_IS_NEW_BRANCH
当前分支是否属于一个新创建的分支,默认为 false
# CNB_IS_NEW_BRANCH_WITH_UPDATE
当前分支是否属于一个新创建的分支,且带有新 commit,默认为 false
# CNB_IS_RETRY
当前构建是否由 rebuild
触发
# HUSKY_SKIP_INSTALL
兼容 ci 环境下 husky
# CNB_VSCODE_WEB_URL
VSCode
远程开发地址,仅声明了 services
: vscode
时存在
# CNB_ISSUE_ID
- 对于
issue.*
触发的构建,值为Issue
全局唯一ID
- 否则值为空字符串
# CNB_ISSUE_IID
- 对于
issue.*
触发的构建,值为Issue
在仓库中的编号iid
- 否则值为空字符串
# CNB_ISSUE_TITLE
- 对于
issue.*
触发的构建,值为Issue
的title
- 否则值为空字符串
# CNB_ISSUE_DESCRIPTION
- 对于
issue.*
触发的构建,值为Issue
的description
- 否则值为空字符串
# CNB_ISSUE_OWNER
- 对于
issue.*
触发的构建,值为Issue
作者用户名 - 否则值为空字符串
# CNB_ISSUE_STATE
- 对于
issue.*
触发的构建,值为Issue
状态:open
、closed
- 否则值为空字符串
# 使用环境变量
除在了 shell 脚本中可以使用环境变量以外,在内置任务的 options
属性里也是可以使用的
# 在 script 中使用
main:
push:
- stages:
- name: test internal env
script: echo $CNB_BRANCH
# 在内置任务 options
中使用
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}
# 阻止环境变量替换
默认情况下,处在 options 中的字段,会在任务执行阶段,进行环境变量替换。
比如
options:
shell: |
echo '$CNB_EVENT'
echo '$myVar'
替换完为
options:
shell: |
echo 'push'
echo ''
如果不希望 myVar
被替换,可以通过 \$
阻止替换
options:
shell: |
echo '$CNB_EVENT'
echo '\$myVar'
替换完为
options:
shell: |
echo 'push'
echo '$myVar'
# 声明环境变量
- 通过
env
声明环境变量 - 在
Pipeline
里声明的环境变量对当前Pipeline
有效 - 在
Job
里声明的环境变量对当前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}
# 导入环境变量
- 通过
imports
指向一个private
的 Git 仓库文件,可实现将私有票据注入到环境变量 - 当
env
和imports
的key
冲突时,优先使用env
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
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
# 修改环境变量
通过 exports
属性可以在 Job
中修改、新增、删除环境变量,生命周期为当前 Pipeline
。
exports:
from-key: to-key
exports
是一个对象,其中对象的key
为本Job
的输出对象的key
,value
为映射的环境变量名称。from-key
指定转换前的key
,支持环境变量,支持深层取值。to-key
指定转换后的key
# 从 Jobs 返回值导出环境变量
script
自定义脚本任务,可设置的属性有:
code
: 返回码stdout
: 标准输出stderr
: 标准错误info
: 标准输出、标准错误,按时序的混合体提示
注意:推荐使用
printf "%s" "hello\nworld"
来输出变量,以消除标准输出流最后的换行符,同时保留\n
等转义字符。
包含 if
、ifModify
、ifNewBranch
等判断逻辑时,可设置的属性有:
skip
: 如果没有跳过,那么返回空字符串;如果跳过了,那么返回因何跳过if
、ifModify
、ifNewBranch
。
- name: use if
if: exit -1
exports:
skip: REASON
- name: tell last
script: echo $REASON # $REASON 的值为 if 这个字符串
# 增删改查环境变量
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:
# 新增
code: CUSTOM_ENV_DATE_CODE
# 修改
info: CUSTOM_ENV_DATE_INFO
# 删除
CUSTOM_ENV_FOR_DELETE: null
# 删除
# CUSTOM_ENV_FOR_DELETE:
- name: tag
type: xxx:xxxx
exports:
#支持对象深层取值
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
# 在内置任务中修改环境变量
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