管道传输

set_env

# <key>: The name of the environment variable e.g. pipeline-namespace, app-name
# <value>: Value of the key
set_env <key> # reads <value> from `stdin`
set_env <key> <value>

保存任意字符串，可通过 get_env. 后续调用检索。

如果参数 <value> 缺失，set_env 则从标准输入读取。set_env 同时支持一次性设置多个键值对。

示例：

# set value provided as argument
set_env app-name "my-app-name"

# set value provided via stdin
echo "my-app-name" | set_env app-name
set_env my-api-key < /config/my-api-key

# set multiple key value pairs
set_env key-1 "value-1" \
  key-2 "value-2" \
  key-n "value-n"

set_envc

# <key>: The name of the environment variable e.g. pipeline-namespace, app-name
# <value>: Value of the key
set_envc <key> # reads <value> from `stdin`
set_envc <key> <value>

保存一个不可变的任意字符串，该字符串可通过 get_env. 后续检索。 一旦通过 保存 set_envc，就无法通过后续的 set_env / set_envc 调用进行修改。

如果参数 <value> 缺失，set_envc 则从标准输入读取。set_envc 同时支持一次性设置多个键值对。

• 一旦通过 设置 set_envc，该键就无法通过后续调用 set_envc 或 进行 set_env 覆盖。
• 已通过 set_env 设置的变量，无法再用 set_envc. 覆盖。

示例：

# set value provided as argument
set_envc app-name "my-app-name"

# set value provided via stdin
echo "my-app-name" | set_envc app-name
set_envc my-api-key < /config/my-api-key

# set multiple key value pairs
set_envc key-1 "value-1" \
  key-2 "value-2" \
  key-n "value-n"

格特恩夫

# <key>: The name of the environment variable e.g. pipeline-namespace, app-name
get_env <key> [default]

打印存储的配置值 (按以下顺序):

• 如果 set_env 先前与 key 一起使用，那么它将检索该值
• 它尝试读取文件 $CONFIG_DIR/$key (CONFIG_DIR 缺省为 /config)
• 它打印指定的缺省值 (如果有)
• 它打印一条错误消息，并返回非零退出码

示例：

get_env app-name "default-app-name"

list_env

list_env

显示 "set_env 进程中保存的密钥和环境变量。

示例：

list_env

设置秘密

# <key>: The name of the secret e.g. artifactory-token, (short-lived) iam-token
# <value>: Value of the secret
set_secret <key> # reads <value> from `stdin`
set_secret <key> <value>

保存一个秘密，以后可以用 get_secret.

如果缺少 <value> 参数，set_secret 将从标准输入中读取。

• 与 set_env 不同，set_secret 不支持同时传递多个要设置的键值对。
• set_secret 设置的内容不会被序列化，因此无法跨子管道/异步管道运行。
• 建议在调用时禁用调试日志，以确保即使在调试日志中也不会显示保存的秘密内容。
• 确保脚本和任何逻辑都不依赖于 set_secret 的任何输出（有一条打印语句利用 ::add-mask:: 功能 屏蔽了密文值）

示例：

# set value provided as argument
set_secret app-name "my-app-name"

# set value provided via stdin
echo "my-secret-content" | set_secret my-secret
set_secret my-api-key < /config/my-api-key

get_secret

# <key>: The name of the secret set with set_secret or set as Secure Value in pipeline UI
get_secret <key> [default]

读取存储的秘密值（按此顺序）：

• 如果 set_secret 先前与 key 一起使用，那么它将检索该值
• 它尝试读取文件 $SECRET_CONFIG_DIR/$key (SECRET_CONFIG_DIR 缺省为 /config/secure-properties)
• 它打印指定的缺省值 (如果有)
• 它打印一条错误消息，并返回非零退出码

示例：

get_secret cookie-token "default-token"

get_secret specific-account-ibmcloud-api-key "$(get_secret ibmcloud-api-key "")"

list_secrets

list_secrets

在管道用户界面中显示 set_secret 进程中保存的密钥和安全值类型环境变量。

示例：

list_secrets

删除秘密

remove_secret <key>

该命令将取消设置存储在 pipelinectl 中的密文，这些密文是使用 set_secret 保存的。

保存文件

# <key>:  File name
# <value>: Path, where the file will be stored
save_file <key> <value>

保存稍后可使用 load_file 检索的任意文件。

不支持目录。

示例：

save_file some_config ./config.yaml

加载文件

# <key>:  File name
load_file <key>

将保存的文件打印到 stdout。

示例：

load_file some_config > some_config.yaml

萨沃雷波

# <key>:  Key of the repository e.g. repository name
# <prop>: Type of the property, e.g. url, branch, commit etc.
# <value>: Value of the property
save_repo <key> [<prop>=<value> ...]

向管道注册新存储库或更新现有存储库。

受支持的属性:

• url：可用于克隆存储库的 URL。
• path: 克隆的存储库相对于工作空间根的位置。

其他属性名称也可以使用，但为了避免命名冲突，它们必须以特定于服务的标识作为前缀，例如，使用 foo，使用 my-service.foo。

示例：

save_repo app_ui "url=${REPO_URL}" "path=app_ui_repo"
save_repo app_ui "branch=${REPO_BRANCH}"
save_repo app_ui "commit=${REPO_SHA}"

# any additional property can be added
save_repo app_ui "commit=${REPO_SHA}"

command_with_large_output | save_repo app_ui "issues"

# this also works with multiple properties,
# but stdin can provide value for only a single one
command_with_large_output | save_repo app_ui "issues" "result=success" "commit=${REPO_SHA}"

save_repo app_ui "bar="
load_repo app_ui bar # returns an empty string

仓库列表

list_repos

列出存储到 stdout 的存储库的 <key>。

示例：

list_repos
# returns the list of stored repository keys to stdout for example:
#  app_ui
#  app_repo

加载仓库

# <key>: Key of the repository, e.g. repository name
# <prop>: Name of the property, e.g. commit, branch, url
load_repo <key> [<prop>]

打印资源库指定属性的值。 仅提供版本库时，列出版本库的所有可用属性。 如果提供的存储库或属性无效，则返回错误信息，表明未找到匹配的属性。

描述：

• 打印存储库指定属性的值，如果 和 值。
• 列出版本库的所有可用属性，当只有 提供。
• 如果提供的 无效。

示例 1：获取特定属性

REPO_SHA=$(load_repo app_ui commit)

例 2：列出给定资源库的所有属性

REPO_SHA=$(load_repo app_ui)

与 "list_repos 一起使用，用于检索属性值

#
# iterate over all repos and print their URLs
#
while read -r key; do
  url=$(load_repo $key url)
  echo "Repository saved as '$key' is at: '$url'"
done < <(list_repos)

将以下行输出到控制台:

检索特定属性时：

 Repository saved as 'my-frontend' is at: 'github.com/my-team/frontend'
 Repository saved as 'my-backend' is at: 'github.com/my-team/backend'

当列出某个资源库的所有属性时：

 Properties available for '$key'.

保存结果

# <stage>: Stage name e.g. test, detect-secrets, static-scan
# <path>: Path where will be stored the file, string
save_result  <stage> <path>

保存任意测试，扫描阶段的结果文件。 稍后可使用 load_result 检索此文件。 缺省情况下，将以工作空间相对路径作为键保存数据。

通过使用 PIPELINECTL_USE_PATH_AS_KEY 功能标志，将使用提供的路径作为键来保存数据。

示例：

#
# save the contents of the file ./results/mocha_results.json
# as an entry named "mocha_results.json" for the "test" stage
#
save_result test ./results/mocha_results.json

#
# save the contents of the file ../data/coverage.xml
# as an entry named "coverage.xml" for the "test" stage
#
save_result test ../data/coverage.xml

#
# Using the `PIPELINECTL_USE_PATH_AS_KEY` environment variable
# save the contents of the file ../data/coverage.xml
# as an entry named "../data/coverage.xml" for the "test" stage
#
PIPELINECTL_USE_PATH_AS_KEY=1 save_result test ../data/coverage.xml

结果列表

# <stage>: Stage name
list_results <stage>

列出阶段的已保存文件名。

示例：

list_results test
# mocha_results.json
# coverage.xml

加载结果

# <stage>: Stage name e.g. test, detect-secrets, static-scan
# <file>: File name e.g. mocha_results.json
load_result <stage> <file>

将保存的文件密钥打印到 stdout。 缺省情况下，键是 save_result 中提供的文件路径的工作空间相对路径。 使用 PIPELINECTL_USE_PATH_AS_KEY 功能标志，键是 save_result 中提供的文件路径的路径。 要获取确切的密钥列表，请使用 list_results。

示例：

load_result test mocha_results.json

#
# Using the `PIPELINECTL_USE_PATH_AS_KEY` environment variable
PIPELINECTL_USE_PATH_AS_KEY=1 load_result test ../data/coverage.xml

与 list_results 一起使用

#
# iterate over all results stored for "test"
# and write them to the filename they were registered with
#
while read -r filename; do
  load_result test "$filename" > "./$filename"
done < <(list_results test)

save_工件

# <key>: Key of the artifact e.g. app-image, baseimage etc.
# <prop>: Type of property e.g. name, type, tags, signature
# <value>: Value of the property
save_artifact <key> [<prop>=<value> ...]

向管道注册新的构建工件或更新现有构建工件。

save_artifact ui_service "name=us.icr.io/team_namespace/ui_service:2.4.3"
save_artifact ui_service "type=image"

# any additional property can be added
save_artifact ui_service "tags=latest,2.4.3,feat-something"

# later, when the image was signed, and we have signature data
save_artifact ui_service "signature=${SIGNATURE}"

command_with_large_output | save_artifact ui_service "issues"

# this also works with multiple properties,
# but stdin can provide value for only a single one
command_with_large_output | save_artifact ui_service "issues" "result=success" "signature=${SIGNATURE}"

save_artifact ui_service "bar="
load_artifact ui_service bar # returns an empty string

list_工件

list_artifacts

列出 stdout 的已存储工件的 <key>。

示例：

list_artifacts
# returns the list of stored artifact keys to stdout for example:
#
# ui_service
# app_service

load_工件

# <key>: Name of the artifact e.g. app-image, baseimage etc.
# <prop>: Type of property e.g. name, type, tags, signature
load_artifact <key> [<prop>]

描述：

• 打印存储库指定属性的值，如果 和 值。
• 列出版本库的所有可用属性，当只有 提供。

示例 1：获取特定属性

SIGNATURE=$(load_artifact ui_service signature)

Example2:列出给定人工制品的所有属性：

load_artifact ui_service

与 "list_repos 一起使用，用于检索属性值

#
# iterate over all artifacts and print their image names
#
while read -r key; do
  image=$(load_artifact $key name)
  echo "Artifact saved as '$key' is named: '$image'"
done < <(list_artifacts)

将以下行输出到控制台:

检索特定属性时：

 Artifact saved as 'ui_service' is named: 'us.icr.io/team_namespace/ui_service:2.4.3'
 Artifact saved as 'backend_service' is named: 'us.icr.io/team_namespace/backend_service:2.4.3'

当列出某一人工制品的所有属性时：

 Properties available for 'ui_service': name, type, tags, signature

序列化

将 pipelinectl 数据序列化为可传输的 JSON 文件，以用作管道 Webhook 触发器的有效内容。 它可以序列化由 save_repo 设置的存储库，由 save_artifact 设置的工件以及由 set_env 设置的环境变量。

(可选) 标志:

--all-repos         # all the repository information set by `pipelinectl`
--all-artifacts     # all the artifacts information set by `pipelinectl`

示例：

以下代码将所有存储库，所有工件和 <env_variable1>，<env_variable2> 保存到 foo.json 文件中:

pipelinectl serialize --all-repos --all-artifacts <env_variable1> <env_variable2> > foo.json
```此命令不是别名。 您明确需要 `pipelinectl`。
{: note}


### 反序列化 {: #deserialize}

将 `pipelinectl` 从 JSON 反序列化为文件，因此 `pipelinectl` 可以在触发的管道中工作。 使用 `pipelinectl serialize` 命令序列化的 JSON 作为自变量。

示例：

```bash {: codeblock}
pipelinectl deserialize ./foo.json
```该命令不是别名，需要明确 `pipelinectl`。
{: note}


## 低级方法 {: #low-level-methods}

这些方法只是为了完整而暴露的。 仅在极少数情况下使用这些方法。

### 普数据 {: #put_data}

```bash {: codeblock}
# <key>: Name of the data
# <prop>: Type of property e.g. name, type, tags, signature
# <value>: Value of the property
put_data <key> <prop> <value>

将 key 定义的条目的 prop 设置为 value。

Get_data

# <key>: Key of data
# <prop>: Type of property e.g. name, type, tags, signature
# <value>: Value of the property
get_data <key>
get_data <key> <prop>

打印 key 定义的条目的 prop。 如果未提供 prop，那么它将返回 key 的所有 prop。 当 key 没有 prop 时，返回非零退出代码。

保存资产

# <prop>: Type of property; for example, uri, id, blob
# <value>: Value of the property
save_asset <prop1> <value1> blob <json_string or path to a json file>
save_asset <prop1> <value1> <prop2> <value2> blob <json_string  or path to a json file>

将资产信息保存到 pipelinectl 存储器以在整个管道中可访问。 允许任意数目的属性。 但是，blob 是一个必须传递的保留属性，其对应的值应该是一个有效 json 文件的文件路径或一个有效的 json 字符串。 save_asset 属性创建不可改变的条目。 不能对 <prop> <value> 对的同一组合调用两次。

加载资源

# <prop>: Type of property; for example, uri, id
# <value>: Value of the property
load_asset # retrieves all assets stored by save_asset
load_asset <prop1> <value1> # retrieves one asset that matches prop1 = value1 saved during save_asset
load_asset <prop1> <value1> <prop2> <value2> # retrieves one asset that matches prop1 = value1 AND prop2 = value2 saved during save_asset

检索与提供的 <prop> <value> 对匹配的资产。 如果在不使用 <prop> <value> 组合的情况下进行调用，那么它将检索在 JSON 数组内的管道中使用 save_asset 保存的所有资产。 blob 属性是保留属性，因此不能将其用作 load_asset 的匹配属性。

萨克证据

# <prop>: Type of property; for example, blob, sha
# <value>: Value of the property
save_evidence <prop1> <value1> blob <json_string  or path to a json file>
save_evidence <prop1> <value1> <prop2> <value2> blob <json_string  or path to a json file>

将证据信息保存到 pipelinectl 存储器中，以便在整个管道中都可访问这些信息。 允许任意数目的属性。 但是，blob 属性是一个必须传递的保留属性，其对应的值应该是一个有效 json 文件的文件路径或一个有效的 json 字符串。 save_evidence 属性创建不可改变的条目。 不能对 <prop> <value> 对的同一组合调用两次。

加载证据

# <prop>: Type of property; for example, id, sha
# <value>: Value of the property
load_evidence # retrieves all evidences that are stored by save_evidence
load_evidence <prop1> <value1> # retrieves one evidence that matches prop1 = value1 saved during save_evidence
load_evidence <prop1> <value1> <prop2> <value2> # retrieves one evidence that matches prop1 = value1 AND prop2 = value2 saved during save_evidence

检索与提供的 <prop> <value> 对匹配的证据。 如果在不使用 <prop> <value> 组合的情况下进行调用，那么它会在 JSON 数组内的管道中检索使用 save_evidence 保存的所有证据。 blob 属性是保留属性，因此不能将其用作 load_evidence 的匹配属性。

删除证据

delete_evidences # deletes all the evidences stored inside pipelinectl so far using save_evidence

此命令将清除存储在 pipelinectl 中的所有证据，这些证据是使用 save_evidence 保存的。

save_string (不推荐)

不推荐使用 save_string，请改为使用 set_env。

save_string <key> <value>

保存稍后可使用 load_string 检索的任意字符串。

load_string (不推荐)

不推荐使用 load_string，请改为使用 get_env。

load_string <key>

打印存储在 key 中的字符串。