DevSecOps命令行界面

DevSecOps CLI 采用合规解决方案IBM Cloud®DevSecOps参考实现；例如，左移参考管道。有关左移合规架构的更多信息，请参阅 DevSecOps和Continuous Delivery。

CLI 界面

CLI 在命令行上使用多部分结构，您必须按以下顺序指定此结构:

cocoa <command> <subcommand> [options]

对 CLI 的基本调用。
主命令，通常对应于左移体系结构所使用的服务或模块; 例如，变更请求，库存或 tekton。
指定要执行的操作的子命令。
操作所需的 CLI 选项。如果遵循步骤 1-3，那么可以按任意顺序指定 CLI 选项。

某些命令使用环境变量来获取 API 密钥或配置命令行中未提供的选项值。在运行该命令之前，需要导出这些变量。

命令行选项可以采用各种类型的输入值，例如数字，字符串，布尔值，数组和 JSON 对象。选项类型取决于您指定的命令。使用 cocoa <command> <subcommand> --help 可查看选项类型。

重试失败的 API 调用

可可 CLI 会重试任何失败且响应状态为 5xx 的 API 调用三次。您可以通过提供以下环境变量来覆盖此行为:

MAX_RETRY_ATTEMPTS-Cocoa CLI 在放弃之前进行的重试次数。例如，MAX_RETRY_ATTEMPTS=5
RETRY_STATUS_CODE-发生重试的响应状态码。例如，RETRY_STATUS_CODE=409,422,500 以重试这三个状态码。

export MAX_RETRY_ATTEMPTS=5                 # Retry API calls 5 times.
export RETRY_STATUS_CODE=409,422,500            # Retry API calls for response codes 409, 422 and 500.

重试在时间上成倍间隔，因此设置较高的重试尝试会导致重试间隔更远。

命令执行的耗用时间

通过将 DISPLAY_ELAPSED_TIME 设置为非空字符串，可可 CLI 可以显示任何命令的耗用时间 (以秒计)，如下所示:

export DISPLAY_ELAPSED_TIME=1`                # Display a snippet showing the total execution time of the cli command, example `Elapsed time: 5.32 seconds`

CLI 命令

虽然ServiceNow有记录，但默认不支持IBM CloudDevSecOps参考实现。但是，如果你想了解如何使用ServiceNow与DevSecOps参考实现，获取帮助IBM Cloud加入我们的开发团队松弛。

可可拉取请求命令

可可检查拉取-请求-核准

检查落实散列上的拉取请求的核准状态。如果未核准拉取请求，那么将在指定的存储库中创建新的事件问题。该命令可以识别标有标签的紧急拉取请求，在这种情况下，它的退出代码为 0。

必需的环境变量:

GHE_TOKEN=              # Github Enterprise API Token (Optional if you are using --git-token-path field)
GHE_ORG=                # The owner of the repository
GHE_REPO=               # The repository name
INCIDENT_ISSUE_REPO=    # The incident issue repo name
EMERGENCY_LABEL=        # Emergency Label name
GIT_COMMIT=             # Commit hash of the Pull Request

选项：

--label                 # Label to add to possible pr incident issue
--git-provider          # SCM provider (GitHub)
--git-token-path        # (Optional) GitHub Token's path
--git-api-url           # (Optional) GitHub API url

如果你正在使用GitHub,您可以使用 --git-token-path 字段来设置您的GitHub代币和 --git-api-url 字段设置#GitHub EnterpriseAPI URL 而不是 GHE_TOKEN 和 GH_URL 环境变量。如果同时提供了这两个值，那么 --git-token-path 和 --git-api-url 优先。

运行命令:

cocoa check pull-request-approval

可可检查拉取请求状态

检查给定拉取请求的状态和存储库设置。

分支保护: 用于禁用强制推送，阻止删除分支以及 (可选) 在合并之前需要状态检查的规则。
落实状态检查: 用于标记具有 error，failure，pending 或 success 状态的落实的外部服务，这将反映在涉及这些落实的拉取请求中。
检查运行: 执行持续集成，代码整理或代码扫描服务并提供有关落实的详细反馈的应用程序。

必需的环境变量:

REQUIRED_CHECKS=        # Minimum required checks to be compliant set by client
GIT_BRANCH=             # Branch name for branch protection check
GIT_COMMIT=             # Commit hash of the Pull Request
GHE_TOKEN=              # Github Enterprise API Token (Optional if you are using --git-token-path field)
GHE_ORG=                # The owner of the repository
GHE_REPO=               # The repository name

如果你正在使用GitHub,您可以使用 --git-token-path 字段来设置您的GitHub代币和 --git-api-url 字段设置#GitHub EnterpriseAPI URL 而不是 GHE_TOKEN 和 GH_URL 环境变量。如果同时提供了 GHE_TOKEN GH_URL 和 --git-token-path --git-api-url 对，那么 --git-token-path 和 --git-api-url 优先。

REQUIRED_CHECKS 示例：

  [
    {
      "type": "status",
      "name": "unit-test",
      "params": {
        "name": "travis/ci"
      }
    },
    {
      "type": "check-run",
      "name": "secret-detection",
      "params": {
        "name": "detect-secrets"
      }
    },
    {
      "type": "branch-protection",
      "name": "code review",
      "params": {
        "checks": ["travis/ci", "detect-secrets"]
      }
    },
    {
      "type": "check-run",
      "name": "open-source-license-scan",
      "params": {
        "name": "ossc/ci"
      }
    }
  ]

运行命令:

 cocoa check pull-request-status

cocoa change-request 命令

cocoa change-request 命令支持以下变更管理提供程序:

ServiceNow V1
ServiceNow V3

您可以通过将 --provider 选项与以下值配合使用来指定提供程序: servicenow (缺省值) 或 servicenow-v3。

每个提供程序都需要不同的环境变量配置:

servicenow:
- SERVICENOW_TOKEN- ServiceNow V1 API 令牌
- SERVICENOW_URL- ServiceNow V1 API URL
servicenow-v3:
- PNP_IBMCLOUD_API_KEY-用于访问 ServiceNow v3 端点的 API 密钥 (如果未提供) 回退到 IAM_ACCESS_TOKEN
- IAM_ACCESS_TOKEN-IBMCloud IAM OAuth 令牌
- SERVICENOW_URL- ServiceNow V3 API URL
github-enterprise:
- GHE_TOKEN- GitHub Enterprise 令牌
- GITHUB_CHANGE_MANAGEMENT_REPO- GitHub 更改管理存储库
- GITHUB_CHANGE_MANAGEMENT_ORG- GitHub 变更管理组织

可可更改-请求获取

从 ServiceNow API 查询变更请求，并将其保存到文件或将其打印到控制台。

ServiceNow v1 或 v2:

SERVICENOW_TOKEN= # ServiceNow API Token
SERVICENOW_URL=   # ServiceNow API URL

ServiceNow v3:

SERVICENOW_URL=       # ServiceNow API URL

ServiceNow v3:

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

Gitlab 所需的环境变量:

GITLAB_TOKEN= # Gitlab token. (Optional if you are using --git-token-path)
GITLAB_URL=   # Change management API URL (Optional if you are using --git-api-url)

选项：

--change-request-id='CHGXXXXXX'  # (Required) The Change Request ID to query from ServiceNow.
--output='filename.json'         # (Optional) If provided, the Change Request data will be written to this file.
--provider='servicenow'          # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', default: 'servicenow')

运行命令:

# Read Change Request with number 'CHG123456' and output the JSON Data to the console.
$ cocoa change-request get --change-request-id='CHG123456'

# Read Change Request with number 'CHG123456' and output the JSON Data to the file named 'cr.json'.
$ cocoa change-request get --change-request-id='CHG123456' --output='cr.json'

# Read Change Request with number 'CHG123456' using the ServiceNow v3 API
$ cocoa change-request get --change-request-id='CHG123456' --provider='servicenow-v3'

可可更改-请求创建

创建变更请求并将其发布到 ServiceNow API。

两种用法:

从 CLI 选项提供所有必需的 CR 字段。

选项：

--assigned-to      # A ServiceNow validated user (defaults to value found in the pull request)
--system           # the name of the system in ServiceNow
--impact           # impact explanation (defaults to value found in th pull request)
--outage-duration  # duration of the outage (format: 'd HH:mm:ss' or 'none')
--priority         # change priority, valid options: critical, high, moderate, low, planning (defaults to value found in the pull request)
--environment      # the environment for the deployment
--purpose          # purpose explanation (default to value found in the pull request)
--description      # description of the change
--backout-plan     # description of the backout plan (defaults to the value found in the PR)
--planned-start    # planned start time of the change (required format: YYYY-MM-DD HH:mm:ss, e.g 2020-05-13 13:00:12, in UTC)
--planned-end      # planned end time of the change (required format: YYYY-MM-DD HH:mm:ss, e.g 2020-05-13 13:00:12, in UTC)
--deployment-ready # readiness for deployment (choices: 'yes', 'no', default: 'yes')
--type             # change request type, option: standard, emergency
--provider         # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', 'github-enterprise', 'gitlab' default: 'servicenow')
--pipeline-name    # (Optional) name of the pipeline used for identifying the pipeline
--pipeline-version # (Optional) version of pipeline used (value must match regular expression [0-9.]+)

提供要从中解析变更请求数据的文件名。需要 JSON 格式。

选项：

--file --f         # json file name to parse the cr data from
--provider         # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', default: 'servicenow')

示例文件:

{
  "type": "emergency",
  "assignedto": "alexandra.szanto@ibm.com",
  "backoutplan": "rollback",
  "priority": "critical",
  "purpose": "bugfix",
  "description": "test description",
  "environment": "crn:v1:bluemix:public::ch-ctu-2::::",
  "impact": "bug",
  "system": "devopsinsights",
  "outageduration": "0 00:00:00",
  "plannedstart": "2020-10-05 14:48:00",
  "plannedend": "2020-10-05 14:49:00",
  "deploymentready": "yes",
}

ServiceNow v1 或 v2:

SERVICENOW_TOKEN=   # ServiceNow API Token
SERVICENOW_URL=     # ServiceNow API URL

ServiceNow v3:

SERVICENOW_URL=       # ServiceNow API URL

ServiceNow v3:

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

运行命令:

 cocoa change-request create --file=test.json

或

$ cocoa change-request create \
  --assigned-to=<your-ibm-email> \
  --system=<servicenow-configuration-item> \
  --impact=<impact description> \
  --outage-duration='0 00:00:00' \
  --priority=<the-priority> \
  --environment=<involved-environment> \
  --purpose=<purpose-explanation> \
  --description=<description-of-the-change> \
  --backout-plan=<description-of-a-backout-plan> \
  --planned-start='2020-05-13 13:00:12' \
  --planned-end='2020-05-13 13:10:12' \
  --deployment-ready=<yes/no> \
  --type=<change-type> \

可可更改-请求更改-状态-实现

通过 ServiceNow API 将变更请求的状态更改为 implement。

选项：

--provider         # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', default: 'servicenow')

必需的环境变量，而不考虑提供程序:

CHANGE_REQUEST_ID=  # ID of the Change Request

必需的环境变量 (如果您正在使用 ServiceNow v1 或 v2 提供程序):

SERVICENOW_TOKEN=    # ServiceNow API Token
SERVICENOW_URL=      # ServiceNow API URL

必需的环境变量 (如果您正在使用 ServiceNow v3 提供程序):

SERVICENOW_URL=       # ServiceNow API URL

其他环境变量 (如果您正在使用 ServiceNow v3 提供程序):

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise 提供程序所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

运行命令:

 cocoa change-request change-state-to-implement

可可更改-请求关闭

通过 ServiceNow API 关闭变更请求。您可以使用 --close-notes 选项附加“关闭注释”，并使用 --close-category 选项指定“关闭类别”。

选项：

--close-category  # Choices: "successful" (default), "successful_issues", "unsuccessful", "cancelled"
--close-notes     # String, defaults to "Deployment done."
--provider        # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', default: 'servicenow')

必需的环境变量，而不考虑提供程序:

CHANGE_REQUEST_ID=  # ID of the Change Request

必需的环境变量 (如果您正在使用 ServiceNow v1 或 v2 提供程序):

SERVICENOW_TOKEN=    # ServiceNow API Token
SERVICENOW_URL=      # ServiceNow API URL

必需的环境变量 (如果您正在使用 ServiceNow v3 提供程序):

SERVICENOW_URL=       # ServiceNow API URL

其他环境变量 (如果您正在使用 ServiceNow v3 提供程序):

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise 提供程序所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

运行命令:

 cocoa change-request close

可可变更-请求检查-核准

查询变更请求的核准状态。如果变更请求是紧急情况，那么该命令不会失败，但会提示进行追溯核准。

选项：

--provider         # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', default: 'servicenow')

必需的环境变量，而不考虑提供程序:

CHANGE_REQUEST_ID=  # ID of the Change Request

必需的环境变量 (如果您正在使用 ServiceNow v1 或 v2 提供程序):

SERVICENOW_TOKEN=    # ServiceNow API Token
SERVICENOW_URL=      # ServiceNow API URL

必需的环境变量 (如果您正在使用 ServiceNow v3 提供程序):

SERVICENOW_URL=       # ServiceNow API URL

其他环境变量 (如果您正在使用 ServiceNow v3 提供程序):

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise 提供程序所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

运行命令:

 cocoa change-request check-approval

可可变化-请求准备

创建更改请求数据并将其打印到控制台或文件。

必需的环境变量:

GHE_TOKEN=              # Github Enterprise API Token (only required when parsing from pr)
GHE_ORG=                # The owner of the repository (optional, when --org is not provided)
GHE_REPO=               # The repository name (optional, when --repo is not provided)
EMERGENCY_LABEL=        # Emergency Label (optional, when --emergency-label is not provided)

可以从拉取请求主体解析以下字段:

--assigned-to
--impact
--priority
--purpose
--backout-plan
--type
--customer-impact
--deployment-impact

如果是使用 CLI 选项提供的，那么 CLI 选项会覆盖拉取请求中找到的值。如果提供了所有这些属性，那么不解析 pr，不需要 --org，--repo 和 GHE_TOKEN。

选项：

--org              # github organization where the parsed pr is (only needed if fields are parsed from pr, defaults to GHE_ORG)
--repo             # github repository name whre the parsed pr is (only needed if fields are parsed from pr, defaults to GHE_REPO)
--pr               # the pull request number to parse (mutually exclusive with sha and branch)
--sha              # infer the pr number from hash (mutually exclusive with pr and branch)
--branch           # infer PR based on the last merged pr into this branch (defaults to master)
--assigned-to      # A ServiceNow validated user (defaults to value found in the pull request)
--system           # the name of the system in ServiceNow
--impact           # implact explanation (defaults to value found in th pull request)
--outage-duration  # duration of the outage
--planned-start    # planned start time of the change (required format: YYYY-MM-DD HH:mm:ss, e.g 2020-05-13 13:00:12, in UTC)
--planned-end      # planned end time of the change (required format: YYYY-MM-DD HH:mm:ss, e.g 2020-05-13 13:00:12, in UTC)
--priority         # change priority, valid options: critical, high, moderate, low, planning (defaults to value found in the pull request)
--environment      # the environment for the deployment
--purpose          # purpose explanation (default to value found in the pull request)
--backout-plan     # description of the backout plan (defaults to the value found in the PR)
--deployment-ready # description of the change
--type             # change request type, option: standard, emergency
--emergency-label  # emergency label to look for in the pull request
--file             # file name to print the cr data to (optional, prints to stdout by default)
--service-environment # service environment of the change, valid options: production, pre_prod
--service-environment-detail # brief description of the service environment where change is deployed.
--pipeline-name    # (Required) name of the pipeline used (for example 'onepipeline | continuous-delivery')
--pipeline-version # version of pipeline used (for example '9.22.3')
--validation-record # Pre-prod change request numbers or NA if there is no pre-prod change request for the deployment

运行命令:

$ cocoa cr prepare \
  --org=<github-organization> \
  --repo=<github-repo-name> \
  --pr=<pr number>

可可变更-请求-核准

请求核准处于新状态的记录，但未请求核准。运行时，记录遵循手动核准路径。

选项：

--crid="<ID>"
# or
--change-request-id="<ID>"
--provider         # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', default: 'servicenow')

必需的环境变量 (如果您正在使用 ServiceNow v1 或 v2 提供程序):

SERVICENOW_TOKEN=    # ServiceNow API Token
SERVICENOW_URL=      # ServiceNow API URL

必需的环境变量 (如果您正在使用 ServiceNow v3 提供程序):

SERVICENOW_URL=       # ServiceNow API URL

其他环境变量 (如果您正在使用 ServiceNow v3 提供程序):

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise 提供程序所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

运行命令:

 cocoa change-request request-approval --crid="<insert-change-request-id-here>"

可可更改-请求任务添加

不推荐使用此命令，将在 2.0.0中除去此命令。请改为使用 cocoa change-request attachment add !

将变更任务添加到特定变更请求。

选项：

--description      # A more detailed description for the Change Task. [string]
--name             # Name of the Change Task. [string] [required]
--data             # Data for the Change Task or a path prefixed with @ to read the data from. [string] [default: "@/dev/stdin"]
--provider         # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', default: 'servicenow')

必需的环境变量 (如果您正在使用 ServiceNow v1 或 v2 提供程序):

SERVICENOW_TOKEN=    # ServiceNow API Token
SERVICENOW_URL=      # ServiceNow API URL

必需的环境变量 (如果您正在使用 ServiceNow v3 提供程序):

SERVICENOW_URL=       # ServiceNow API URL

其他环境变量 (如果您正在使用 ServiceNow v3 提供程序):

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise 提供程序所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

运行命令:

$ cocoa change-request task add "CHGXXXXXXX" \
        --name='<task-name>' \
        --data='<data-for-the-task>'

$ cat data.txt | cocoa change-request task add "CHGXXXXXXX" --name='<task-name>'

$ cocoa change-request task add "CHGXXXXXXX" \
        --name='<task-name>' \
        --data='@<path/to/file>'

可可更改-请求任务获取

不推荐使用此命令，将在 2.0.0中除去此命令。请改为使用 cocoa change-request attachment get !

获取变更请求的特定变更任务。

选项：

--provider         # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', default: 'servicenow')

必需的环境变量 (如果您正在使用 ServiceNow v1 或 v2 提供程序):

SERVICENOW_TOKEN=    # ServiceNow API Token
SERVICENOW_URL=      # ServiceNow API URL

必需的环境变量 (如果您正在使用 ServiceNow v3 提供程序):

SERVICENOW_URL=       # ServiceNow API URL

其他环境变量 (如果您正在使用 ServiceNow v3 提供程序):

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise 提供程序所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

运行命令:

 cocoa change-request task get "CHGXXXXXXX" "CTASKXXXXXXX"

可可更改-请求任务列表

不推荐使用此命令，将在 2.0.0中除去此命令。请改为使用 cocoa change-request attachment list !

列出变更请求的变更任务。

选项：

--provider         # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', default: 'servicenow')

必需的环境变量 (如果您正在使用 ServiceNow v1 或 v2 提供程序):

SERVICENOW_TOKEN=    # ServiceNow API Token
SERVICENOW_URL=      # ServiceNow API URL

必需的环境变量 (如果您正在使用 ServiceNow v3 提供程序):

SERVICENOW_URL=       # ServiceNow API URL

其他环境变量 (如果您正在使用 ServiceNow v3 提供程序):

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise 提供程序所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

运行命令:

 cocoa change-request task list "<insert-change-request-id-here>"

可可更改-请求任务更新

不推荐使用此命令，将在 2.0.0中除去此命令。请改为使用 cocoa change-request attachment update !

更新特定变更请求中的变更任务。

选项：

--change-request-id  # The change request the change task belongs to [string] [required]
--change-task-id     # The change task id to be updated [string] [required]
--description        # A more detailed description for the Change Task. [string]
--data               # Data for the Change Task or a path prefixed with @ to read the data from. [string]
--provider           # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', default: 'servicenow')

必需的环境变量 (如果您正在使用 ServiceNow v1 或 v2 提供程序):

SERVICENOW_TOKEN=    # ServiceNow API Token
SERVICENOW_URL=      # ServiceNow API URL

必需的环境变量 (如果您正在使用 ServiceNow v3 提供程序):

SERVICENOW_URL=       # ServiceNow API URL

其他环境变量 (如果您正在使用 ServiceNow v3 提供程序):

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise 提供程序所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

运行命令:

$ cocoa change-request task update
        --change-request-id='CHGXXXXXXX' \
        --change-task-id='CTASKXXXXXXX' \
        --data='<data-for-the-task>' \
        --description='<description>'

$ cat data.txt | cocoa change-request task update --change-request-id='CHGXXXXXXX' --change-task-id='CTASKXXXXXXX' --data='@/dev/stdin'

$ cocoa change-request task update --change-request-id='CHGXXXXXXX' --change-task-id='CTASKXXXXXXX' --data='@<path/to/file>'

可可更改-请求附件添加

将变更附件添加到特定变更请求。

选项：

--description      # A more detailed description for the Change Task. [string]
--name             # Name of the Change Task. [string] [required]
--data             # Data for the Change Task or a path prefixed with @ to read the data from. [string] [default: "@/dev/stdin"]
--provider         # (Optional) Change Management service provider (choices: 'servicenow', 'github-enterprise', 'servicenow-v3', default: 'servicenow')

必需的环境变量 (如果您正在使用 ServiceNow v1 或 v2 提供程序):

SERVICENOW_TOKEN=    # ServiceNow API Token
SERVICENOW_URL=      # ServiceNow API URL

必需的环境变量 (如果您正在使用 ServiceNow v3 提供程序):

SERVICENOW_URL=       # ServiceNow API URL

其他环境变量 (如果您正在使用 ServiceNow v3 提供程序):

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise 提供程序所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

运行命令:

$ cocoa change-request attachment add "CHGXXXXXXX" \
        --name='<attachment-name>' \
        --data='<data-for-the-attachment>'

$ cat data.txt | cocoa change-request attachment add "CHGXXXXXXX" --name='<attachment-name>'

$ cocoa change-request attachment add "CHGXXXXXXX" \
        --name='<attachment-name>' \
        --data='@<path/to/file>'

可可更改-请求附件获取

获取变更请求的特定变更附件。

选项：

--provider         # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', default: 'servicenow')

必需的环境变量 (如果您正在使用 ServiceNow v1 或 v2 提供程序):

SERVICENOW_TOKEN=    # ServiceNow API Token
SERVICENOW_URL=      # ServiceNow API URL

必需的环境变量 (如果您正在使用 ServiceNow v3 提供程序):

SERVICENOW_URL=       # ServiceNow API URL

其他环境变量 (如果您正在使用 ServiceNow v3 提供程序):

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise 提供程序所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

运行命令:

 cocoa change-request attachment get "CHGXXXXXXX" "CTASKXXXXXXX"

可可更改-请求附件列表

列出变更请求的变更附件。

选项：

--provider         # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', default: 'servicenow')

必需的环境变量 (如果您正在使用 ServiceNow v1 或 v2 提供程序):

SERVICENOW_TOKEN=    # ServiceNow API Token
SERVICENOW_URL=      # ServiceNow API URL

必需的环境变量 (如果您正在使用 ServiceNow v3 提供程序):

SERVICENOW_URL=       # ServiceNow API URL

其他环境变量 (如果您正在使用 ServiceNow v3 提供程序):

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise 提供程序所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

运行命令:

 cocoa change-request attachment list "<insert-change-request-id-here>"

可可更改-请求附件更新

更新特定变更请求中的变更附件。

选项：

--change-request-id  # The change request the change task belongs to [string] [required]
--change-task-id     # The change task id to be updated [string] [required]
--description        # A more detailed description for the Change Task. [string]
--data               # Data for the Change Task or a path prefixed with @ to read the data from. [string]
--provider           # (Optional) Change Management service provider (choices: 'servicenow', 'servicenow-v3', default: 'servicenow')

必需的环境变量 (如果您正在使用 ServiceNow v1 或 v2 提供程序):

SERVICENOW_TOKEN=    # ServiceNow API Token
SERVICENOW_URL=      # ServiceNow API URL

必需的环境变量 (如果您正在使用 ServiceNow v3 提供程序):

SERVICENOW_URL=       # ServiceNow API URL

其他环境变量 (如果您正在使用 ServiceNow v3 提供程序):

PNP_IBMCLOUD_API_KEY= # API Key to access ServiceNow v3 endpoints, if not provided, falls back to IAM_ACCESS_TOKEN
IAM_ACCESS_TOKEN=     # Access token obtained from the IAM service

GitHub Enterprise 提供程序所需的环境变量:

GHE_TOKEN=    # Github Enterprise API Token (only required when parsing from pr)
GITHUB_CHANGE_MANAGEMENT_ORG=   # The owner of the repository (optional, when --org is not provided)
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name (optional, when --repo is not provided)

运行命令:

$ cocoa change-request attachment update
        --change-request-id='CHGXXXXXXX' \
        --change-attachment-id='CTASKXXXXXXX' \
        --data='<data-for-the-attachment>' \
        --description='<description>'

$ cat data.txt | cocoa change-request attachment update --change-request-id='CHGXXXXXXX' --change-attachment-id='CTASKXXXXXXX' --data='@/dev/stdin'

$ cocoa change-request attachment update --change-request-id='CHGXXXXXXX' --change-attachment-id='CTASKXXXXXXX' --data='@<path/to/file>'

可可证据命令

可可证据创建

根据指定的选项创建证据并将其保存到文件或将其打印到控制台。

运行命令:

$ cocoa evidence create \
  --namespace=[choices: "ci", "cd"] \               # Pipeline type the evidence was collected from
  --evidence-name=<evidence-name> \                 # It will be used to name evidence-file in git
  --evidence-type=<evidence-type> \                 # e.g: com.ibm.unit_test
  --evidence-type-version=<evidence-type-version> \
  --result=[choices: "failure", "success"] \        # The result of the scan/test
  --issue=<issue-url> \                             # e.g: --issue=foo --issue=bar || --issue=foo
  --artifact=<artifact_url> <artifact_hash>\        # Url and hash pair(s) to the test artifact(s)
  --log=<log_url> <log_hash> \                      # Url and hash pair(s) to the log(s)
  --pipeline-id=<pipeline-id> \
  --pipeline-run-id=<pipeline-run-id> \
  --pipeline-run-url=<pipeline-run-url> \
  --toolchain-crn=<toolchain-crn> \                 # Name of the toolchain cloud resource
  --output=<filename>                                # If present, the evidence will be saved to the given file.

除了 issue，log 和 artifact 之外，还可以从环境变量设置 CLI 选项。必须为多个问题或工件提供多个问题或工件标志。例如：

 cocoa evidence create --artifact <url> <hash>  --artifact <url> <hash> --issue <issue-url> --issue <issue-url>

artifact 由指向工件文件的 URL 和散列组成，必须以与先前示例中相同的方式提供这些 URL。

可可证据格式-摘要

将证据摘要格式化为人类可读格式。可以将其反馈到变更请求内容中。

运行命令:

$ cocoa evidence format-summary \
  --input=<filepath> \          # (default: -, referring to stdin) If present, the formatted evidence will be read from the given file.
  --output=<filepath>           # (default: -, referring to stdout) If present, the formatted evidence will be saved to the given file.

# Reading from stdin and printing to stdout:
$ cat raw-summary.json | cocoa evidence format-summary -i - -o - | tee formatted-summary.txt
$ cat raw-summary.json | cocoa evidence format-summary | tee formatted-summary.txt
# Reading to and from file:
$ cocoa evidence format-summary --input=raw-summary.json --output=formatted-summary.txt

可可证据降价-摘要

将证据摘要格式化为可以作为 GitHub 拉取请求注释提供的 Markdown 格式。

输入是原始摘要，可以采用以下两种格式之一:

JSON 格式的摘要 ( cocoa evidence summarize 命令的输出)。
聚集摘要，这是单个应用程序摘要的 JSON 数组。

当聚集摘要作为输入传递时，输出会根据摘要中的应用程序对证据状态进行分组。

可选标志:

--detailed: 如果标志设置为 true (缺省情况下，对于已删除的向下摘要，true 设置为 false )，那么将生成详细的 Markdown 摘要。

运行命令:

$ cocoa evidence markdown-summary \
  --input=<filepath> \          # (default: -, referring to stdin) If present, the formatted evidence will be read from the given file.
  --output=<filepath>           # (default: -, referring to stdout) If present, the formatted evidence will be saved to the given file.

# Reading from stdin and printing to stdout:
$ cat raw-summary.json | cocoa evidence markdown-summary -i - -o - | tee markdown-summary.md
$ cat aggr-summary.json | cocoa evidence markdown-summary | tee markdown-summary.md
# Reading to and from file:
$ cocoa evidence markdown-summary --input=raw-summary.json --output=markdown-summary.md

可可证据上载

将证据上载到指定的后端。后端可以是不同的证据锁定程序类型，例如 Object Storage，GitHub 或 DevOps Insights。不同的储物柜需要提供不同的参数。

尚不支持 DevOps Insights。

必需选项:

--backend

必需的环境变量:

EVIDENCE_REPO_ORG=  # Evidence repo org (Required if you are using 'git' backend)
EVIDENCE_REPO_NAME= # Evidence repo name (Required if you are using 'git' backend)

必需的环境变量（如果您使用GitHub:

GHE_TOKEN=          # Github Enterprise API Token (Optional if you are using --git-token-path)

必需的环境变量 (如果使用的是 Cloud Object Storage):

COS_API_KEY=        # Cloud Object Storage API Key (Required if you are using 'cos' backend)
COS_BUCKET_NAME=    # Bucket Name where the evidence will be uploaded in the COS Instance (Required if you are using 'cos' backend)
COS_ENDPOINT=       # The COS API Endpoint matching the region where the bucket is located (Required if you are using 'cos' backend)

如果要使用 github，请使用 --git-token-path 字段来设置 GitHub 令牌，并使用 --git-api-url 字段来设置 # GitHub Enterprise API URL 而不是 GHE_TOKEN 和 GH_URL 环境变量。如果同时提供了这两个值，那么 --git-token-path 和 --git-api-url 优先。

运行命令:

$ cocoa evidence upload

$ cocoa evidence upload \
  --backend=[choices: "git", "insights", "cos"] \   # e.g. --backend=cos,git,insights
  --namespace=[choices: "ci", "cd"] \               # Pipeline type the evidence was collected from
  --evidence-name=<evidence-name> \                 # It will be used to name evidence-file in git
  --evidence-type=<evidence-type> \                 # e.g: com.ibm.unit_test
  --evidence-type-version=<evidence-type-version> \
  --result=[choices: "failure", "success"] \        # The result of the scan/test
  --issue=<issue-url> \                             # e.g: --issue=foo --issue=bar || --issue=foo
  --artifact=<artifact_url> <artifact_hash>\        # Url and hash pair(s) to the test artifact(s)
  --log=<log_url> <log_hash> \                      # Url and hash pair(s) to the log(s)
  --pipeline-id=<pipeline-id> \
  --pipeline-run-id=<pipeline-run-id> \
  --pipeline-run-url=<pipeline-run-url> \
  --toolchain-crn=<toolchain-crn>                   # Name of the toolchain cloud resource

除了 backend，issue，log 和 artifact 之外，还可以从环境变量设置 CLI 选项。必须为多个问题或工件提供多个问题或工件标志。例如：

 cocoa evidence upload --backend=git --artifact <url> <hash>  --artifact <url> <hash> --issue <issue-url> --issue <issue-url> --git-provider='github'

artifact 由指向工件文件的 URL 和散列组成，以与先前示例中相同的方式提供这些项。

可可证据汇总

从证据锁定程序查询证据，并根据其内容生成证据摘要。后端可以是不同的证据锁定程序类型，例如 Object Storage 或 GitHub。目前，支持 git 和 cos 作为后端。不同的储物柜需要提供不同的参数。

Git的必需环境变量:

EVIDENCE_REPO_ORG=  # Use this environment varibale to provide the owner organisation of the evidence repository (Required if you are using 'git' backend)
EVIDENCE_REPO_NAME= # Use this environment varibale to provide the name of the evidence repository (Required if you are using 'git' backend)
PIPELINE_RUN_ID=    # Can be used instead of '--pipeline-run-id' option
TOOLCHAIN_CRN=      # Can be used instead of '--toolchain-crn' option

必需的环境变量（如果您使用GitHub:

GHE_TOKEN=          # Github Enterprise API Token (Optional if you are using --git-token-path)

Git的选项:

--backend           # (Required) Specifies the type of locker from where the evidences are queried
--repo              # Evidence Repositories name (can be substituted by EVIDENCE_REPO_NAME environment variable)
--org               # Evidence Repositories owner organisation (can be substituted by EVIDENCE_REPO_ORG environment variable)
--pipeline-run-id   # (Required)
--toolchain-crn     # (Required)
--prefix-list       # (Required) a list of paths separated by comma where evidences can be found in the repository
--output            # (Optional) file name to write the evidence summary into
--git-token-path    # (Optional) Github Token's path
--git-api-url       # (Optional) Github API url

如果要使用 github，请使用 --git-token-path 字段来设置 GitHub 令牌，并使用 --git-api-url 字段来设置 # GitHub Enterprise API URL 而不是 GHE_TOKEN 和 GH_URL 环境变量。如果同时提供了 GHE_TOKEN GH_URL 和 --git-token-path --git-api-url 对，那么 --git-token-path 和 --git-api-url 优先。

缺省情况下，每次调用时的 CLI 都会确保您使用最新版本的 Git 锁定程序。可以通过将 COCOA_USE_CACHE 设置为除 0，false，no 或 n 以外的任何值来禁用此行为。在这种情况下，CLI 使用其内部高速缓存来查找证据 (速度更快)，但结果可能是过时的。

必需的环境变量 (如果使用的是 Cloud Object Storage):

COS_API_KEY=      # COS api token
COS_BUCKET_NAME=  # COS bucket name where evidences are stored
COS_ENDPOINT=     # COS endpoint where the bucket is available
PIPELINE_RUN_ID=  # Can be used instead of '--pipeline-run-id' option
TOOLCHAIN_CRN=    # Can be used instead of '--toolchain-crn' option

cos 的选项:

--backend         # (Required) Specifies the type of locker from where the evidences are queried
--pipeline-run-id # (Required)
--toolchain-crn   # (Required)
--prefix-list     # (Required) a list of paths separated by comma where evidences can be found in the repository
--output          # (Optional) file name to write the evidence summary into

运行命令:

# Save the evidence summary to 'summary.json' file.
$ cocoa evidence summarize \
  --backend='git' \
  --pipeline-run-id='id-123-123' \
  --toolchain-crn='crn-123-123' \
  --prefix-list='raw/ci/pipeline-run-id-1,raw/ci/pipeline-run-id-2' \
  --output='summary.json'

# Print the evidence summary to the console
$ cocoa evidence summarize \
  --backend='git' \
  --pipeline-run-id='id-123-123' \
  --toolchain-crn='crn-123-123' \
  --prefix-list='raw/ci/pipeline-run-id-1,raw/ci/pipeline-run-id-2'

可可工件命令

可可工件上载

将工件上载到指定的后端。后端可以是不同的证据锁定程序类型，例如 Object Storage，GitHub 或 DevOps Insights。不同的储物柜需要提供不同的参数。

选项：

--backend           # (Required) Specifies the types of lockers we upload the artifact ('cos', 'git')
--pipeline-run-id   # The ID of the PipelineRun running the CLI command
--namespace         # Specifies the pipeline the evidence is collected from
--upload-path       # If present, this overrides the artifact name with the specified value
--is-summary        # If present, this uploads the artifact to the location where evidence summary is usually stored

Git的选项:

--git-token-path    #(Optional) Github Token's path
--git-api-url           #(Optional) Github API url

必需的环境变量:

PIPELINE_RUN_ID=    # Can be used instead of '--pipeline-run-id' option
NAMESPACE=          # Can be used instead of '--namespace' option

必需的环境变量 (如果使用的是 "git" 提供程序):

EVIDENCE_REPO_ORG=  # The Git repo org (Required if you are using 'git' backend)
EVIDENCE_REPO_NAME= # The Git repo name (Required if you are using 'git' backend)

必需的环境变量（如果您使用GitHub:

GHE_TOKEN=          # Github Enterprise API Token (Optional if you are using --git-token-path)

必需的环境变量 (如果使用的是 Cloud Object Storage):

COS_API_KEY=        # Cloud Object Storage API Key (Required if you are using 'cos' backend)
COS_BUCKET_NAME=    # Bucket Name where the artifact will be uploaded in the COS Instance (Required if you are using 'cos' backend)
COS_ENDPOINT=       # The COS API Endpoint matching the region where the bucket is located (Required if you are using 'cos' backend)

运行命令:

$ cocoa artifact upload

$ cocoa artifact upload \
  --backend=[choices: "git", "cos"] \ # e.g. --backend=cos,git
  --pipeline-run-id=<pipeline-run-id> # can be substituted by PIPELINE_RUN_ID
  --namespace=[choices: "ci", "cd"] \ # Pipeline type the evidence was collected from, can be substituted by NAMESPACE
  --is-summary        # If present, this uploads the artifact to the location where evidence summary is usually stored
  <file-path>

还可以从环境变量 ( backend 和 upload-path 除外) 设置 CLI 选项。

可可集合-状态

设置落实的状态。当前实现在 GitHub上进行测试。请参阅有关 GitHub 状态的文档。

必需的环境变量:

GHE_ORG=      # Github organization/username
GHE_REPO=     # Github repository
GHE_COMMIT=   # Github commit hash

必需的环境变量（如果您使用GitHub:

GHE_TOKEN=    # Github token (Optional if you are using --git-token-path)

Git的选项:

--git-token-path    #(Optional) GitHub token's path
--git-api-url       #(Optional) GitHub API url

运行命令:

$ cocoa set-status \
 --state="pending" \
 --targetURL="https://cloud.ibm.com/devops/pipelines/tekton/some-toolchain/runs/some-pipelinerun/lint/lint?env_id=ibm:yp:us-south" \
 --context="tekton/lint" \
 --description="Tekton linter is running."

可可库存命令

可可库存加

向库存存储库添加值。使用 name 选项创建文件 (如果该文件不存在)，否则将覆盖该文件。

必需的环境变量:

GHE_ORG=     # Github Organization (required if --org option is not specified).
GHE_REPO=    # Github Repository (required if --repo option is not specified).

必需的环境变量（如果您使用GitHub:

GHE_TOKEN=    # Github Enterprise API Token(Optional if you are using --git-token-path)

Git的选项:

--git-token-path    #(Optional) Github Token's path
--git-api-url           #(Optional) Github API url

表 1. Git 的选项
选项	描述	值类型	必需值或缺省值
工件	工件名称。	字符串	必需
版本	应用程序的版本。	字符串	必需
存储库 URL	应用程序的存储库。	字符串	必需
管道运行标识	管道运行的标识。	字符串	必需
落实-沙	从中构建工件的应用程序存储库的落实	字符串	必需
名称	工件所属的应用程序的名称	字符串	必需
构建号	构建的编号。	数字	必需
组织 (org)	拥有库存存储库的 GitHub 组织。	字符串
repo	清单存储库的名称。	字符串
app-工件	JSON 格式的任意应用程序内容	字符串
类型	工件的类型	字符串	必需
sha256	工件的 sha256 散列	字符串	必需
起源	指向工件的 URL (例如，已构建的图像)	字符串	必需
特征符	工件的特征符	字符串	必需
环境	在其中添加条目的环境的名称。	字符串	“主”
Git-provider *	Git 版本控制服务提供者。	字符串 *	"github"
git-token-path	要从中读取私钥的 Git 令牌路径	字符串
Git-api-url	Git API URL	字符串

运行命令:

$ cocoa inventory add \
  --artifact=cocoa-script-cli \
  --type=type \
  --sha256=786800e8e48938664fe2397ca14ab8dabd48f34656ef5cfda4143b4519cb714f \
  --signature=123123valid \
  --name=cocoa-cli \
  --repository-url=http://validURL.com \
  --commit-sha=8e86dc4647ce28632103dce46b756c70d339349a \
  --version=v4 \
  --build-number=33 \
  --pipeline-run-id=123123valid \
  --git-token-path=./git-token \
  --org=test \
  --app-artifacts='{"app": "test", "some_value": "value"}' \
  --repo=repository

$ cocoa inventory add \
  --environment=environment \
  --artifact=foo-helm-chart/foo/chart.yaml \
  --repository-url=http://validURL.com \
  --commit-sha=786800e8e48938664fe2397ca14ab8dabd48f34656ef5cfda4143b4519cb714f \
  --build-number=33 \
  --pipeline-run-id=123123valid \
  --version=v4 \
  --name=chart

可可库存获取

从库存存储库获取条目。目标可以是特定版本或环境。使用 --version 或 --environment，并且仅使用其中一个。如果缺少 --property 选项，那么将打印库存条目的整个内容。

必需的环境变量（如果您使用GitHub:

GHE_TOKEN=    # Github Enterprise API Token (Optional if you are using --git-token-path)

Git的选项:

--git-token-path       #(Optional) Github Token's path
--git-api-url          #(Optional) Github API url

运行命令:

# Uses the environment as target, and pretty-prints only a given property of the inventory entry to the console.
$ cocoa inventory get \
  --org='Github-ID' \
  --repo='compliance-inventory-repo' \
  --entry='hello-compliance-app' \
  --environment='master' \
  --property='name'

# Uses the version as target, and pretty-prints the whole content of the inventory entry to the console.
$ cocoa inventory get \
  --org='Github-ID' \
  --repo='compliance-inventory-repo' \
  --entry='hello-compliance-app' \
  --version='v1'

可可库存获取-沙

从库存存储库中按标签或环境获取最新落实散列。使用 --label 或 --environment，并且仅使用其中一个。

必需的环境变量（如果您使用GitHub:

GHE_TOKEN=    # Github Enterprise API Token (Optional if you are using --git-token-path)

Git的选项:

--git-token-path    #(Optional) Github Token's path
--git-api-url       #(Optional) Github API url

如果要使用 github，请使用 --git-token-path 字段来设置 GitHub 令牌，并使用 --git-api-url 字段来设置 # GitHub Enterprise API URL 而不是 GHE_TOKEN 和 GH_URL 环境变量。如果提供了 GHE_TOKEN GH_URL 和 --git-token-path --git-api-url 对，那么 --git-token-path 和 --git-api-url 优先。

运行命令:

# Get the latest commit hash of the staging branch
$ cocoa inventory get-sha \
  --org='Github-ID' \
  --repo='compliance-inventory-repo' \
  --environment='staging'

# Get the commit hash of the "pipeline-run-id" label
$ cocoa inventory get-sha \
  --org='Github-ID' \
  --repo='compliance-inventory-repo' \
  --label='pipeline-run-id'

可可库存标签

向库存条目添加标签，或在库存中移动标签。目标可以是特定分支或其他标签上的最新落实。

选项：

--org          # The Github organisation which owns the inventory repository.
--repo         # The name of the inventory repository.
--environment  # The inventory branch
--to-label     # Another label in the inventory, that will be looked up/removed

必需的环境变量:

GHE_ORG=     # Github Organization (required if --org option is not specified).
GHE_REPO=    # Github Repository (required if --repo option is not specified).

必需的环境变量（如果您使用GitHub:

GHE_TOKEN=    # Github Enterprise API Token (Optional if you are using --git-token-path)

Git的选项:

--git-token-path    #(Optional) Github Token's path
--git-api-url           #(Optional) Github API url

运行命令:

# label the latest state on "staging" branch
$ cocoa inventory label add \
  --org='Github-ID' \
  --repo='compliance-inventory-repo' \
  --environment='staging' \
  "new-label-to-add"

# attach a label to another label (to the same commit)
$ cocoa inventory label add \
  --org='Github-ID' \
  --repo='compliance-inventory-repo' \
  --to-label="some-label" \
  "new-label-to-add"

# move or create the `staging_latest` label to another label (to the same commit)
$ cocoa inventory label move \
  --org='Github-ID' \
  --repo='compliance-inventory-repo' \
  --to-label="some-label" \
  "label-to-move"

促进可可盘存

将库存中的条目从一个环境提升到另一个环境。源环境可以是分支或标记。

必需的环境变量:

GHE_ORG=          # Github Organization (required if --org option is not specified).
GHE_REPO=         # Github Repository (required if --repo option is not specified).
PIPELINE_RUN_ID=  # Can be used instead of --pipeline-run-id (either the option or the variable is required).

必需的环境变量（如果您使用GitHub:

GHE_TOKEN=    # Github Enterprise API Token (Optional if you are using --git-token-path)

Git的选项:

--git-token-path    #(Optional) Github Token's path
--git-api-url           #(Optional) Github API url

运行命令:

$ cocoa inventory promote \
  --org='Github-ID' \
  --repo='compliance-inventory-repo' \
  --source='master' \
  --target='prod' \
  --priority='Critical' \
  --assigned-to='employee@ibm.com' \
  --description='desc' \
  --purpose='purpose' \
  --impact='impact' \
  --customer-impact='impact' \
  --deployment-impact='small' \
  --backout-plan='rollback'

cocoa 事件命令

可可事件添加

根据 commit-hash 在管道运行中为失败的任务创建或更新突发事件问题。

选项：

--task              # (Required) The name of the failing task
--commit-hash       # (Required) The commit hash which triggered the pipeline run
--pipeline-run-url  # The pipeline run url where the task ran
--org               # The incident issue repo org
--repo              # The incident issue repo name
--assignee          # (Optional) Assignee(s) for the incident issue (github username) e.g: --assigne=jane-doe --assignee=john-smith
--app-repo-url      # The app repo URL
--label             # Label(s) to add to the incident issue (optional) e.g: --label=foo --label=bar
--git-token-path    # (Optional) Github Token's path
--git-api-url       #(Optional) Github API url

必需的环境变量:

GHE_ORG=                    # Can be used instead of --org (either the option or the variable is required)
GHE_REPO=                   # Can be used instead of --repo (either the option or the variable is required)
PIPELINE_RUN_URL=           # Can be used instead of --pipeline-run-url (either the option or the variable is required)
APP_REPO_URL=               # Can be used instead of --app-repo-url (either the option or the variable is required)

必需的环境变量（如果您使用GitHub:

GHE_TOKEN=    # Github Enterprise API Token (Optional if you are using --git-token-path)

运行命令:

 cocoa incident add --task=<failing-task-name> --commit-hash=<abc123>

可可事件进程

此命令将处理提供的扫描结果，并在提供的存储库中针对每个漏洞创建突发事件问题 (而不是像 cocoa incident add 一样运行每个任务)。如果已存在主题/事件对的问题，那么不会创建新的问题。

如果设置了 --set-grace-period，那么它将创建具有“宽限期”设置的问题，或者更新现有问题以具有“宽限期”。

宽限期设置为 15 天 (如果已启用)。如果在突发事件问题上设置了“豁免”或“宽限期”，那么此检查会列出该问题，但不会将其标记为错误。

在 CR VA 中配置了异常，或者您可以提交事件或 CVE 以进行免除核准。如果已核准，您可以编辑事件问题 (设置 Excempt: **true**)，并链接到已核准的请求。

当前支持的扫描结果文件:

Container Registry VA 扫描 (选项 --type va)
CRA 漏洞扫描 (选项 --type cra)
Xray (选项 --type xray)
OWASP ZAP (选项 --type owasp-zap)
OWASP ZAP UI (选项 --type owasp-zap-ui)
Twistlock (选项 --type twistlock)
同级复审扫描 (选项 --type peer-review)
GoLang 安全扫描 (选项 --type gosec)
SonarQube 扫描 (选项 --type sonarqube)
修补扫描 (选项 --type mend)
Checkov (选项 --type checkov)
针对 Terraform 的 CRA 漏洞扫描 (选项 --type cra-tf)
Terraform 安全扫描 (选项 --type tfsec)
Fips 扫描程序 (选项 --type fips-scanner)
对比 Sast (选项 --type contrast-sast)
检测私钥 (选项 --type detect-secrets)
Sysdig (选项 --type sysdig)

有关 Container Registry VA 和结果格式的详细信息，请参阅 Vulnerability Advisor for IBM Cloud Container Registry。有关 CRA 漏洞扫描程序的更多信息，请参阅配置代码风险分析器文档。

用法：

$ cocoa incident process \
  <options> \
  <path to result file>

选项：

--type             # (Required) Scan type [cra | va]
--subject          # (Required) Subject of scans (repo, or image name)
--drilldown-url    # (Required) URL to the point where the incident was found (can be a pipeline run, a commit hash or an image URL with digest)
--set-grace-period # Should the created incidents have Grace period set
--git-provider     # Git service provider [github] Default is "github"
--org              # The incident issue repository org
--repo             # The incident issue repository name
--label            # Label(s) to add to the incident issue (optional) e.g: --label=foo --label=bar
--assignee         #(Optional) Assignee(s) for the incident issue (github username) e.g: --assignee=jane-doe --assignee=john-smith
--git-token-path   #(Optional) Github Token's path
--git-api-url      #(Optional) Github API url
--custom-exempt-label # (Optional) Defines the custom label with which the incident issue has been marked as exempted
--custom-comment   # (Optional) Additional text to be added to issue comments
--format           # (Optional) Format of the output ("list", "json", default: "list")

必需的环境变量:

INCIDENT_REPO_ORG=        # Can be used instead of --org (either the option or the variable is required)
INCIDENT_REPO_NAME=       # Can be used instead of --repo (either the option or the variable is required)

必需的环境变量（如果您使用GitHub:

GHE_TOKEN=                # Github Enterprise API Token (Optional if you are using --git-token-path)

返回值：

如果未找到任何问题，或者所有发现的问题都设置了“豁免”或 "Grace" 时间段，那么该命令将以零状态退出。
如果发现的任何问题未设置“免除”或“宽限期”，那么该命令将以非零状态退出。
如果格式 == list-该命令列出根据结果文件和主题找到或创建的事件问题 URL。
如果格式为 == json-此命令将打印一个 JSON，其中包含根据结果文件和主题找到，创建和自动关闭的每个问题的结果对象数组 (其他问题信息)。
对应于问题的结果 JSON 对象的结构:

{
 "id": string,
 "due_date": string,
 "severity": ("high", "medium", "low", "critical, "informational"),
 "first_found": "string" (optional),
 "url": string,
 "found_status": ("new", "existing", "autoclosed", "readonly"),
 "has_exempt": boolean
}

运行命令:

$ cocoa incident process \
  --type va \
  --subject us.icr.io/service-image \
  --drilldown-url us.icr.io/service-image@sha256:digest \
  path/to/scan-result.json

可可事件流程-遗留

此命令在提供的存储库中针对扫描文件不可用时的场景创建事件问题。通常，此类场景将是与非漏洞相关的故障，例如单元测试故障，分支保护故障，验收测试故障和映像签名故障。这些故障将是非漏洞，但它们将偏离合规态势。如果已存在事件-主题-工具组合的问题，那么该命令不会创建新的问题。缺省情况下，high 严重性评级设置为已创建的问题。

如果设置了 --set-due-date，那么该命令将创建问题或使用到期日期更新现有问题。根据严重性从问题的宽限期开始计算到期日期。

如果设置了 --close-resolved-issues 标志，那么该命令将搜索与当前运行相同的工具，主题和事件标识的打开问题。如果发现任何问题，那么当 --current-status 作为 success 传递时，该命令将关闭这些问题。

如果设置了 --read-only，那么该命令不会创建新问题或修改现有问题。将处理结果，并针对结果收集现有问题。如果未激活只读方式，那么输出将包含应该在问题中跟踪的问题 URL 列表。

用法：

cocoa incident process-legacy \
  <options>

选项：

--type             # (Required) Tool type
--subject          # (Required) Subject of scans (repo, or image name)
--drilldown-url    # (Required) URL to the point where the incident was found (can be a pipeline run, a commit hash or an image URL with digest)
--set-grace-period # Should the created incidents have Grace period set
--git-provider     # Git service provider [github] Default is "github"
--org              # The incident issue repository org
--repo             # The incident issue repository name
--label            # Label(s) to add to the incident issue (optional) e.g: --label=foo --label=bar
--assignee          #(Optional) Assignee(s) for the incident issue (github username) e.g: --assignee=jane-doe --assignee=john-smith
--git-token-path    #(Optional) Github Token's path
--git-api-url           #(Optional) Github API url
--close-resolved-issues # (Optional) Checking and closing resolved issues
--pipeline-run-url      # (Optional) The url to the pipeline run running the CLI command
--is-prod          # (Optional) Flag for whether or not the command was run in production environment. Default is false.
--read-only        # (Optional) Process result file in read-only mode (return found and existing issues, do not create new ones, set processed status to failure or success). Default is false
--custom-exempt-label # (Optional) Defines the custom label with which the incident has been marked as exempted
--incident-id         # (Required) Defines the incident ID to be used for creating legacy incident
--current-status      # (Required) Current status to be treated as success or failure [choices: "success", "failure"]
--custom-comment   # (Optional) Additional text to be added to issue comments
--format           # (Optional) Format of the output ("list", "json", default: "list")
--additional-comment  # (Optional) Additional comment for the issue on every run

环境变量：

INCIDENT_REPO_ORG=    # Can be used instead of --org (either the option or the variable is required)
INCIDENT_REPO_NAME=   # Can be used instead of --repo (either the option or the variable is required)
# Required Environment Variables, if using GitHub:

GHE_TOKEN=    # Github Enterprise API Token (Optional if using --git-token-path)

如果您正在使用 github，那么可以使用 --git-token-path 字段来设置 GitHub 令牌，并使用 --git-api-url 字段来设置 GitHub Enterprise API URL (缺省为 https://github.ibm.com/api/v3)，而不是 GHE_TOKEN 和 GH_URL 环境变量。如果同时提供了 GHE_TOKEN GH_URL 和 --git-token-path --git-api-url 对，那么 --git-token-path 和 --git-api-url 优先。

返回值：

此命令列出在 --current-status 作为 failure 传入时找到或创建的事件问题 URL。如果 --current-status 作为 failure 传入，那么此命令还会关闭与同一事件-工具-主体集组合匹配的事件问题 URL。
在 --read-only 方式下，如果找不到该突发事件的问题，那么该命令会列出该突发事件的详细信息。
如果未找到任何问题，或者所有发现的问题都设置了豁免标签，那么该命令将以零状态退出。
如果发现的任何问题未设置豁免标签，那么该命令将以非零状态退出。
在 --read-only 方式下，如果发现任何没有问题的新事件，那么该命令将以非零状态退出。
如果格式为 == list-如果 --current-status 作为 failure 传入，那么该命令将列出找到或创建的事件问题 URL。
如果格式为 == json-此命令将打印一个 JSON，其中包含根据结果文件和主题找到，创建和自动关闭的每个问题的结果对象数组 (其他问题信息)。
对应于问题的结果 JSON 对象的结构:

{
 "id": string,
 "due_date": string,
 "severity": ("high", "medium", "low", "critical, "informational"),
 "first_found": "string" (optional),
 "url": string,
 "found_status": ("new", "existing", "autoclosed", "readonly"),
 "has_exempt": boolean
}

运行命令:

$ cocoa incident process-legacy \
   --type jest \
   --subject us.icr.io/service-image \
   --drilldown-url us.icr.io/service-image@sha256:digest \
   --incident-id com.ibm.unit_tests_master \
   --current-status success \
   --close-resolved-issues

可可事件评估

基于 due_date 和免除标签评估问题的状态，并输出问题结果。

用法：

$ cocoa incident evaluate \
  <options> \
  <filePath>

选项：

--git-provider         # Git service provider [github] Default is "github"
--org                  # The incident issue repository org
--repo                 # The incident issue repository name
--filePath             # Path to the JSON file that contains issues to be evaluated
--git-token-path       # (Optional) Github Token's path
--git-api-url          # (Optional) Github API url
--custom-exempt-label  # (Optional) Defines the custom label with which the incident issue has been marked as exempted
--is-prod              # (Optional) Whether or not the command was run in prod environment
--format               # (Optional) Format of the output ("list", "json", default: "list")

必需的环境变量:

INCIDENT_REPO_ORG=        # Can be used instead of --org (either the option or the variable is required)
INCIDENT_REPO_NAME=       # Can be used instead of --repo (either the option or the variable is required)

必需的环境变量（如果您使用GitHub:

GHE_TOKEN=                # Github Enterprise API Token (Optional if you are using --git-token-path)

返回值：

如果找到的所有问题都设置了“豁免”或 "Grace" 时间段，那么该命令将以零状态退出。
如果发现的任何问题未设置“免除”或“宽限期”，那么该命令将以非零状态退出。
结果的 JSON 数组。
对应于问题的结果 JSON 对象的结构。

json
{
  "id": string,
  "due_date": string,
  "severity": ("high", "medium", "low", "critical, "informational"),
  "first_found": "string" (optional),
  "url": string,
  "found_status": ("new", "existing", "autoclosed", "readonly"),
  "has_exempt": boolean
}

运行命令:

$ cocoa incident evaluate \
  --org \
  --repo \
  --git-provider \
  --git-token-path \
  --filePath

cocoa locker 命令

证据锁定程序是 GitHub (Enterprise) 上的 Git 存储库。可以使用 --git-provider (缺省情况下为 github ) 来指定 Git 提供程序。对于这两个提供程序，都需要认证，对于 GitHub，请设置 GHE_TOKEN 环境变量或 --git-token-path 字段。为了GitHub,你还必须指定GitHub实例的位置，通过使用 GH_URL 环境变量或 --git-api-url 字段，但默认为 https://github.ibm.com。

可以使用 --org 和 --repo 或者使用 EVIDENCE_LOCKER_REPO_OWNER 和 EVIDENCE_LOCKER_REPO_NAME 环境变量来设置证据锁定程序存储库的名称。

此外，您还可以将证据和附件上载到 Cloud Object Storage以进行归档。当存在以下环境变量时，将自动执行此操作:

COS_ENDPOINT: 可以在其中访问 Cloud Object Storage 存储区的端点。
COS_BUCKET_NAME: Cloud Object Storage 存储区的名称。
COS_API_KEY: 对 Cloud Object Storage 存储区具有写访问权的 IBM Cloud API 密钥或服务标识 API 密钥。
IBM_AUTH_ENDPOINT: API 密钥可用于生成 IAM 令牌的端点 (缺省为 https://iam.cloud.ibm.com/identity/token){: external}。

cocoa locker asset add < URI >

将资产添加到证据锁定程序。如果资产存在，那么将打印该资产。

选项：

--org              # (Required) Owner of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_OWNER`
--repo             # (Required) Name of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_NAME`
--type             # Type of the asset ( All types are supported )
--version          # Show version number
--format           # Output format ("id", "json", default: "id")
--git-provider     # Git service provider ("github")
--git-token-path   # Git token path to read the secret from
--git-api-url      # Github API url
--related          # The ID of a related asset (default: [])
--date             # Asset creation date
--details          # Additional asset details, as key=value pairs (default: [])
--origin           # Additional details about the origin of the asset, as key=value pairs (default: [])
--dry-run          # Shows what would be added to the locker (default: false)

如果不想将任何内容添加到锁定器，并且要检查将添加到锁定器的内容，请使用 --dry-run 标志。

可以使用 --type 标志指定资产类型。

uri 参数可以是任何有效的 URI，但会特别处理一些格式:

如果 uri 方案为 docker (即，它以 docker:// 开头)，那么命令将采用 --type=image 标志
如果 uri 方案为 git，或者路径以 .git 后缀结束，那么该命令将采用 --type=commit 标志

当 type 为 image 或 commit 时，URI 必须在以下模式上匹配:

对于 commit，URI 必须具有一个片段，该片段必须是 40 个字符的十六进制落实 sha (例如 https://github.ibm.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee)
对于 image，URI 必须包含图像摘要 (例如 docker://us.icr.io/foo/bar:v1.2.3@sha256:0000000011111111222222223333333344444444555555556666666677777777)

当 type 不是 image 或 commit 时，必须显式传递 --type 标志。

可以使用接受 key=value 对的 --details 标志向资产添加更多详细信息。

可以使用 --origin 标志提供有关资产来源的更多详细信息，该标志接受 key=value 对。

将自动选取某些环境变量以添加有关资产来源的详细信息:

设置 TOOLCHAIN_CRN 与指定 --origin toolchain_crn=$TOOLCHAIN_CRN 相同
设置 PIPELINE_ID 与指定 --origin pipeline_id=$PIPELINE_ID 相同
设置 PIPELINE_RUN_ID 与指定 --origin pipeline_run_id=$PIPELINE_RUN_ID 相同

--date 标志可用于覆盖资产创建日期 (缺省为当前时间)，它接受 Date.parse 接受的任何字符串。

可以使用 --related 标志来添加相关资产 (对于多个相关资产，可以多次指定该标志)。可以使用资产的内部标识或其 URI 来指定资产。所有相关资产 ID（整个资产树，直到第一个资产）都将添加到资产 json 中的 parents 字段。

缺省情况下，id 格式 ( --format 标志) 打印所创建资产的内部标识。使用 json 格式时，将以 JSON 对象形式打印整个资产。

运行命令以添加 Git 落实:

$ cocoa locker asset add 'https://github.ibm.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee' \
                         --details tag=v1.2.3

示例输出：

b5bbbbb55555b5555b555b55b5555bb5b555b5b555bb5b55bbb5555fbbbbb

运行命令以添加 Docker 映像:

$ cocoa locker asset add docker://us.icr.io/foo/bar:v1.2.3@sha256:0000000011111111222222223333333344444444555555556666666677777777 \
                         --origin "job_name=my job" \
                         --related https://github.ibm.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee \
                         --format json

示例输出：

{
   "version": "1.1",
   "id": "0000000011111111222222223333333344444444555555556666666677777777",
   "uri": "docker://us.icr.io/foo/bar:v1.2.3@sha256:0000000011111111222222223333333344444444555555556666666677777777",
   "origin": {
    "job_name": "my job",
    "toolchain_crn": "crn:v1:bluemix:public:toolchain:au-syd:a/111111111111c2f2222222222b22a7a63:ac2a22a2-2a2a-2222-aaa2-222aa22a2a2a::",
    "pipeline_run_id": "f333b3bc-3333-3fea-3333-333d3a3b33b3",
    "pipeline_id": "444aaa4a-b4c4-4444-4f4b-aa4444a444a4"
   },
   "details": {
    "registry": "us.icr.io",
    "name": "foo/bar",
    "tag": "v1.2.3",
    "digest": "0000000011111111222222223333333344444444555555556666666677777777"
   },
   "date": "2021-07-15T14:26:06.301Z",
   "type": "image",
   "related": [
    "b5bbbbb55555b5555b555b55b5555bb5b555b5b555bb5b55bbb5555fbbbbb"
   ],
   "parents": [
    "b5bbbbb55555b5555b555b55b5555bb5b555b5b555bb5b55bbb5555fbbbbb"
   ]
}

运行命令以添加发行版:

$ cocoa locker asset add release:my-app@v1.2.3 \
                         --type generic \
                         --date 2021-06-01T12:00:00 \
                         --related docker://us.icr.io/foo/bar:v1.2.3@sha256:0000000011111111222222223333333344444444555555556666666677777777

示例输出：

36d8852458adf44ab236c99beb69d7070d461d39480bc6b8ef7c771bee93cb49%

cocoa locker asset get < URI >

从证据锁定程序中检索资产。

选项：

--org              # (Required) Owner of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_OWNER`
--repo             # (Required) Name of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_NAME`
--type             # Type of the asset
--version          # Show version number
--git-provider     # Git service provider ("github")
--git-token-path   # Git token path to read the secret from
--git-api-url      # Github API url
--format           # Output format ("id", "json", default: "id")

运行命令：

 cocoa locker asset get release:my-app@v1.2.3 --format json

示例输出：

{
   "version": "1.1",
   "id": "36d8852458adf44ab236c99beb69d7070d461d39480bc6b8ef7c771bee93cb49",
   "uri": "release:my-app@v1.2.3",
   "origin": {
    "toolchain_crn": "crn:v1:bluemix:public:toolchain:au-syd:a/111111111111c2f2222222222b22a7a63:ac2a22a2-2a2a-2222-aaa2-222aa22a2a2a::",
    "pipeline_run_id": "f333b3bc-3333-3fea-3333-333d3a3b33b3",
    "pipeline_id": "444aaa4a-b4c4-4444-4f4b-aa4444a444a4"
   },
   "details": {
    "sha": "aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee",
    "repository": "https://github.ibm.com/foo/bar.git",
    "tag": "v1.2.3"
   },
   "date": "2021-07-15T14:26:06.301Z",
   "type": "image",
   "related": ["0000000011111111222222223333333344444444555555556666666677777777"],
   "parents": ["0000000011111111222222223333333344444444555555556666666677777777", "b5bbbbb55555b5555b555b55b5555bb5b555b5b555bb5b55bbb5555fbbbbb"]
}

 cocoa locker asset get docker://us.icr.io/foo/bar:v1.2.3@sha256:0000000011111111222222223333333344444444555555556666666677777777 --format json

示例输出：

{
   "version": "1.1",
   "id": "0000000011111111222222223333333344444444555555556666666677777777",
   "uri": "docker://us.icr.io/foo/bar:v1.2.3@sha256:0000000011111111222222223333333344444444555555556666666677777777",
   "origin": {
    "toolchain_crn": "crn:v1:bluemix:public:toolchain:au-syd:a/111111111111c2f2222222222b22a7a63:ac2a22a2-2a2a-2222-aaa2-222aa22a2a2a::",
    "pipeline_run_id": "f333b3bc-3333-3fea-3333-333d3a3b33b3",
    "pipeline_id": "444aaa4a-b4c4-4444-4f4b-aa4444a444a4"
   },
   "details": {
    "sha": "aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee",
    "repository": "https://github.ibm.com/foo/bar.git",
    "tag": "v1.2.3"
   },
   "date": "2021-07-15T14:26:06.301Z",
   "type": "image",
   "related": [],
   "parents": ["b5bbbbb55555b5555b555b55b5555bb5b555b5b555bb5b55bbb5555fbbbbb"]
}

 cocoa locker asset get https://github.ibm.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee --format json

示例输出：

{
   "version": "1.1",
   "id": "0000000011111111222222223333333344444444555555556666666677777777",
   "uri": "docker://us.icr.io/foo/bar:v1.2.3@sha256:0000000011111111222222223333333344444444555555556666666677777777",
   "origin": {
    "toolchain_crn": "crn:v1:bluemix:public:toolchain:au-syd:a/111111111111c2f2222222222b22a7a63:ac2a22a2-2a2a-2222-aaa2-222aa22a2a2a::",
    "pipeline_run_id": "f333b3bc-3333-3fea-3333-333d3a3b33b3",
    "pipeline_id": "444aaa4a-b4c4-4444-4f4b-aa4444a444a4"
   },
   "details": {
    "sha": "aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee",
    "repository": "https://github.ibm.com/foo/bar.git",
    "tag": "v1.2.3"
   },
   "date": "2021-07-15T14:26:06.301Z",
   "type": "image",
   "related": [],
   "parents": []
}

cocoa locker asset summary get < URI >

从证据锁定程序收集给定资产的证据摘要。

选项：

--scope                   # (Required) Pipeline run ID of the CI piepline where the asset is built
--environment             # (Required) Name of the environment from which evidences are fetched, if the `service-environment` is `pre_prod`       
                            This value must be the same as the `target-environment`. Or, if `service-environment` is `prod`, then this value must be the same as the `source-environment`
--service-environment     # Service environment of the asset get summary in deployed environment
                            (choices: 'pre_prod', 'dev', 'prod',  default: 'pre_prod')
--latest                  # Fetches the latest evidence summary of the asset for the `service-environment`.
                            The summary of the scope passed-in using `--scope` will be excluded. Currently supported for `dev` environment only.

运行命令：

 cocoa locker asset summary get https://github.ibm.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee \
  --scope 11a1aa11-1a11-11a1-aa11-a11a1a1111a1 \
  --environment prod \
  --service-environment prod

运行命令以获取最新的证据摘要，但不包括使用 --scope 传入的范围的证据摘要：

 cocoa locker asset summary get https://github.ibm.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee \
  --scope 11a1aa11-1a11-11a1-aa11-a11a1a1111a1 \
  --environment dev \
  --service-environment dev \
  --latest

cocoa locker asset list < URI >

列出证据锁定程序中的相关资产。

选项：

--org              # (Required) Owner of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_OWNER`
--repo             # (Required) Name of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_NAME`
--type             # Type of the asset
--version          # Show version number
--git-provider     # Git service provider ("github")
--git-token-path   # Git token path to read the secret from
--git-api-url      # Github API url
--format           # Output format ("id", "json", default: "id")

运行命令：

 cocoa locker asset list release:my-app@v1.2.3 --format id --type generic

示例输出：

1122211111122222111111111111111111111111111111666661111111111111
2222222222555552222222222222222333333222222222222222222222222222
3333333337777773333333333333333333333333333333344444433333333333

使用与 jq结合使用的 json 格式运行命令:


 cocoa locker asset list release:my-app@v1.2.3 --format json --type generic | jq -r '.[].uri'

示例输出：

release:my-app@v1.2.3
docker://us.icr.io/foo/bar:v1.2.3@sha256:0000000011111111222222223333333344444444555555556666666677777777
https://github.ibm.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee

可可储物柜证据添加

将证据添加到证据锁定程序。

可以使用标志来指定证据锁定程序。有关更多信息，请参阅 cocoa locker 命令。

可使用以下标志对证据进行配置：

--evidence-type: 用于标识证据类型的字符串 (例如 com.ibm.unit_test)
--evidence-type-version: 用于标识证据详细信息模式 (例如 1.0.0，v2 等) 的字符串

也可以指定一些可选标志:

--date: 证据创建日期 (缺省为当前时间戳记)，接受可使用 Date.parse 解析的字符串。
--details: 可以将证据详细信息指定为 key=value 对，可以多次指定该标志 (例如 --details result=success --details foo=bar 等)。
--origin: 可以使用 key=value 对 (例如 --origin job_id=123 等) 来指定有关证据来源的详细信息。
--asset: 指定哪些资产 (按其 URI 或内部标识) 与证据相关，请参阅 cocoa locker asset 命令。可以多次指定该标志。资产必须已存在于锁定程序中。
--attachment: 指定证据的文件附件。每个附件必须指向现有文件，并且每个附件名称必须唯一 (即，不允许 --attachment a/foo.json --attachment b/foo.json )。
--attachment-url: 指定已存储在证据锁定程序中的附件的 URL。每个 URL 都必须指向唯一附件，确保没有重复项。可以多次指定此标志以包含多个 URL。
--issue: 问题 URL 的列表，可用于跟踪与结果相关的活动。可以多次传递该标志。
--findings-path: 使用此路径来传递 JSON 结果数组，该数组是“事件”进程命令的输出。
--scope: 可用于关联来自多个源的证据的唯一标识。
--comment-on-issues: 使用 --issue 标志向提供的突发事件问题添加包含有关已创建证据的详细信息的注释
- 由于问题可以在 github 上，因此将从问题 URL 解析提供程序
- 每个问题都必须来自同一存储库
- 问题 URL 必须与以下模式匹配:
  - https://<host>/<owner>/<name>/issues/<issue number>-用于 github
- 访问问题存储库所需的环境变量:
  - 如果 urls 指向 github 问题:
    - GH_URL: 可选，缺省为 https://github.ibm.com/api/v3
    - GHE_TOKEN

证据 JSON 中附件的标签信息：

证据 JSON 中的每个附件部分都有一个标签属性来保存有关附件的元数据。标签被分配了一个默认值，该值取决于附件输入是文件路径还是附件 URL。通过添加传递自定义标签 ::label=<value> 在附件路径或附件 URL 的末尾。

示例：

--attachment path/to/attachment::label=label_name- 使用文件创建附件 path/to/attachment 并将标签值设置为 label_name。如果不传递标签，则默认使用文件名作为标签值。
--attachment-url url/of/attachment::label=label_name- 使用 attachment-url 并将标签值设置为 label_name。如果不传递标签，标签值默认为空字符串。

将自动选取某些环境变量以添加有关资产来源的详细信息:

设置 TOOLCHAIN_CRN 与指定 --origin toolchain_crn=$TOOLCHAIN_CRN 相同
设置 PIPELINE_ID 与指定 --origin pipeline_id=$PIPELINE_ID 相同
设置 PIPELINE_RUN_ID 与指定 --origin pipeline_run_id=$PIPELINE_RUN_ID 相同

可以使用以下标志来改变命令的行为:

--dry-run: 不向锁定程序添加任何内容，但显示将添加的内容。
--cache-mode: 类似于干式运行。实际上不会将证据添加到储物柜，而是将附件 (如果有) 添加到储物柜。显示要添加的证据。
--format: 控制输出格式 id 或 json (缺省情况下为 id )。

运行命令以保存 detect-secrets的结果:

$ cocoa locker evidence add --evidence-type com.ibm.detect_secrets \
                            --evidence-type-version 1.0.0 \
                            --details result=success \
                            --asset https://github.ibm.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee

运行命令以保存单元测试结果:

$ cocoa locker evidence add --evidence-type com.ibm.unit_test \
                            --evidence-type-version 1.0.0 \
                            --details failure \
                            --asset https://github.ibm.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee
                            --attachment path/to/results/junit.xml \
                            --issue https://github.ibm.com/foo/bar/issues/123 \
                            --findings-path <path/to/file>

运行该命令以使用证据锁定程序中已存在的附件来创建新证据:

$ cocoa locker evidence add --evidence-type com.ibm.detect_secrets \
                            --evidence-type-version 1.0.0 \
                            --attachment-url https://github.ibm.com/foo/bar/blob/master/raw/attachments/5aa5555aa55aa55a555aa5a5aa555555aaaa5aa5aa5555a55a5aa5aa5a5aaaaa/content
                            --asset https://github.ibm.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee

运行命令保存单元测试结果并为附件添加自定义标签：

$ cocoa locker evidence add --evidence-type com.ibm.unit_test \
                            --evidence-type-version 1.0.0 \
                            --details success \
                            --asset https://github.ibm.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee
                            --issue https://github.ibm.com/foo/bar/issues/123 \
                            --findings-path <path/to/file> \
                            --attachment path/to/results/junit.xml::label=unit-test

cocoa locker evidence get < evidence-id >

从锁定程序中检索证据。

选项：

--org              # (Required) Owner of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_OWNER`
--repo             # (Required) Name of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_NAME`
--git-provider     # Git service provider ("github")
--version          # Show version number
--git-token-path   # Git token path to read the secret from
--git-api-url      # Github API url
--format           # Output format ("json", default: "json")

运行命令：

 cocoa locker evidence get 0000000011111111222222223333333344444444555555556666666677777777

示例输出：

{
   "id": "0000000011111111222222223333333344444444555555556666666677777777",
   "evidence_type_id": "com.ibm.unit_tests",
   "evidence_type_version": "1.0.0",
   "date": "2024-03-27T16:36:48.167Z",
   "origin": {
     "toolchain_crn": "crn:v1:bluemix:public:toolchain:us-south:a/40111714589c4f7099032529b26a7a63:f0ffdc07-616e-40fa-98d5-2f52d5e8ef4d::",
     "pipeline_id": "b313626a-a612-4c98-ae5c-408af7d7ce58",
     "pipeline_run_id": "cadb83be-f00d-44af-95d0-1b49deb8abb5",
     "pipeline_run_url": "https://cloud.ibm.com/devops/pipelines/tekton/b313626a-a612-4c98-ae5c-408af7d7ce58/runs/cadb83be-f00d-44af-95d0-1b49deb8abb5/code-unit-tests/run-stage/?env_id=ibm:yp:us-south",
     "scope": "82aef875749c6386381a3baff8430df6f5ac2e8434cc91e5287ce65bd71a3985"
   },
   "details": {
     "result": "pending",
     "tool": "jest"
   },
   "issues": [],
   "findings": [],
   "attachments": [
      {
       "hash": "9a841ef856a5de813dbe440b102b9bff3ca1831630292cff7323c557704f386b",
       "url": "https://s3.private.us-south.cloud-object-storage.appdomain.cloud/test/assets/9a841ef856a5de813dbe440b102b9bff3ca1831630292cff7323c557704f386b/index.json",
       "label": "unit-test"
     }
   ],
   "assets": [
     {
       "hash": "7d930918fbb8be80f3a5100f0313c5b2518eba22cc915194cf971d4daf5170be",
       "uri": "https://github.ibm.com/one-pipeline/compliance-app-march-2024.git#be44f38ec9b290d4f3d4931b37910effac346441",
       "url": "https://s3.us-south.cloud-object-storage.appdomain.cloud/cocoa-development/assets/7d930918fbb8be80f3a5100f0313c5b2518eba22cc915194cf971d4daf5170be/index.json"
     }
   ]
}

cocoa locker evidence summary < asset-id >

返回一个或多个资产的证据摘要。在命令行上未指定资产时，将从 stdin 读取资产。

可选标志：

--latest-only: 如果较新的证据可用于资产，那么将废弃证据 (缺省情况下，true 设置为 false 以禁用此行为)
--scope: 可多次指定仅具有指定作用域的注意事项证据 (请参阅 evidence add --scope)
--linked-scope：将指定链接范围的证据视为范围。此外，还会将它们添加到返回的证据摘要中的 linked-scopes 属性中。可多次指定。
--check-immutable-storage: 检查每个证据是否也存在于 Cloud Object Storage 存储区中，并受至少 365 天的保留期保护。将 com.ibm.immutable_storage 个证据附加到摘要。
- 请参阅有关如何配置 Cloud Object Storage 存储区的 cocoa locker 部分。
--dry-run: 与 --check-immutable-storage 组合时具有效果。如果使用了 com.ibm.immutable_storage 证据，那么仅会将其追加到摘要中，但不会将其上载到证据锁定程序。
--clone-dir：可选参数，用于确定证据库的克隆路径，默认情况下将克隆 repo /tmp 目录
--initialized：可选标记，假定证据柜已在提供的位置 --clone-dir 或 /tmp/ 中克隆。
--evidences-path：要根据缓存中的本地证据创建摘要，此字段用于提供数组中所有证据所在文件的路径。

运行命令：

$ cocoa locker evidence summary \
    docker://us.icr.io/foo/bar@sha256:1234567812345678123456781234567812345678123456781234567812345678 \
    docker://us.icr.io/baz/quux@sha256:1234567812345678123456781234567812345678123456781234567812345678 \
    --scope 11a1aa11-1a11-11a1-aa11-a11a1a1111a1 \
    --scope 22a2aa22-2a22-22a2-aa22-a22a2a2222a2 \
    --linked-scope 33a3aa33-3a33-33a3-33a3-a33a3a3333a3 \
    --linked-scope 12bqab22-1a23-1a23-1a23-b22a3a2222a3

从 stdin 读取的示例:

$ cat <<EOF | cocoa locker evidence summary
docker://us.icr.io/foo/bar@sha256:1234567812345678123456781234567812345678123456781234567812345678
docker://us.icr.io/baz/quux@sha256:1234567812345678123456781234567812345678123456781234567812345678
EOF

cocoa locker attachment get < attachment-id >

检索先前随 cocoa locker evidence add 一起上载的附件。

选项：

--org              # (Required) Owner of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_OWNER`
--repo             # (Required) Name of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_NAME`
--git-provider     # Git service provider ("github")
--version          # Show version number
--git-token-path   # Git token path to read the secret from
--git-api-url      # Github API url

运行命令以上载附件:

$ cocoa locker evidence add --evidence-type-id com.ibm.unit_test \
                            --evidence-type-version 1.0 \
                            --details result=success \
                            --attachment path/to/junit.xml::label=unit-test

附件上载的输出示例:

{
   ...
   "attachments": [
    {
      "hash": "9a841ef856a5de813dbe440b102b9bff3ca1831630292cff7323c557704f386b",
      "url": "https://s3.private.us-south.cloud-object-storage.appdomain.cloud/test/assets/9a841ef856a5de813dbe440b102b9bff3ca1831630292cff7323c557704f386b/index.json",
      "label": "unit-test"
    }
   ],
   ...
}

运行该命令以获取附件：

 cocoa locker attachment get 5aa5555aa55aa55a555aa5a5aa555555aaaa5aa5aa5555a55a5aa5aa5a5aaaaa

可可储物柜检查

检查锁定程序的必需配置和设置。

目前，只有基于 Cloud Object Storage 的锁定程序具有配置需求:

由于每个证据必须至少保留一年，因此 Cloud Object Storage 存储区必须受保留策略保护。缺省保留期必须大于或等于 365 天。

有关更多信息，请参阅 cocoa locker 命令。

必需的环境变量:

COS_API_KEY=        # Cloud Object Storage API Key
COS_BUCKET_NAME=    # Bucket Name where the evidence will be uploaded in the COS Instance
COS_ENDPOINT=       # The COS API Endpoint matching the region where the bucket is located

运行命令：

 cocoa locker check --provider='cos'

可可储物柜证据检查

根据配置文件 cocoa locker evidence check 中存在的检查来验证所需证据。

必需的环境变量:

选项：

--org              # (Required) Owner of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_OWNER`
--repo             # (Required) Name of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_NAME`
--git-provider     # Git service provider ("github")
--git-token-path   # Git token path to read the secret from
--git-api-url      # Github API URL
--config-path      # (required) use this path to read the config file of all the required evidence check
--summary-path     # (required) use this path to read the summary file of all the evidences
--pre-deployment   # If present, will check only pre deployment checks, defaults to false
--post-deployment  # If present, will check only post deployment checks, defaults to false
--source           # (Applies to config file version 2) If present, is tupple of branch:region information(with region as optional) which will be used to filter the rules against `source_environments` field.
--target           # (Applies to config file version 2) If present, is tupple of branch:region information(with region as optional) which will be used to filter the rules against `target_environments` field.
--pipeline-run-id  # (Applies to config file version 2) If present, is current pipeline_run_id will be used for checking evidences.

运行命令：

 cocoa locker evidence check --summary-path `<summary-path>` --config-path `<config-path>` --pre-deployment --post-deployment --source `<source_branch:region>` --target `<target_branch:region>` --pipeline-run-id `<current_pipeline-run-id>`

可可储物柜证据发布

将证据发布到 Git 和 Cloud Object Storage (COS) 后端 (如果配置了 COS)。

cocoa locker evidence publish 用于批量处理证据。

配置 COS 所需的环境变量:

COS_API_KEY=        # Cloud Object Storage API Key
COS_BUCKET_NAME=    # Bucket Name where the evidence will be uploaded in the COS Instance
COS_ENDPOINT=       # The COS API Endpoint matching the region where the bucket is located

选项：

  --version         # Show version number                                
  --help            # Show help                                          
  --git-provider    # Git provider of the evidence locker ("github", "gitlab")
  --org             # (Required) Owner of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_OWNER`            
  --repo            # (Required) Name of the evidence locker repo, defaults to `EVIDENCE_LOCKER_REPO_NAME`              
  --git-token-path  # Git token path to read the secret from              
  --git-api-url     # Git API URL                                         
  --evidences-path  # (Required) Use this path to read the evidences to be published
  --commit-message  # (Optional) Commit message suffix to be used for the commit to the git repository

运行命令：

$ cocoa locker evidence publish \
      --org=<github-organization> \
      --repo=<github-repo-name> \
      --git-provider github \
      --evidences-path <path/to/file>

cocoa tekton 命令

可可特克顿 get-pipeline-logs

为管道运行中的每个步骤创建日志文件，并将其保存到目录中。使用环境变量 (PIPELINE_ID 或 PIPELINE_RUN_ID) 或使用显式标志 (--pipeline-id 或 --pipeline-run-id) 覆盖环境变量。也可以通过提供 --task-name 和 --step-name 标志在每个任务和每个步骤的级别上检索日志文件。

如果提供了 --task-name，那么该命令将尝试为给定任务名称的每个步骤拉取并创建日志文件。

如果 --step-name 随 --task-name 一起提供，那么该命令将为所提供的 task-name. --step-name 的特定步骤创建日志文件，而不使用 --task-name 是无效的命令特征符。

选项：

-o --output-dir       # (Required) Specifies the directory where the logs will be saved
   --pipeline-id      # ID of the pipeline
   --pipeline-run-id  # ID of the pipeline run
-u --use-task-ref     # (Optional) Can be used to override the default name of the pipeline task to the taskRef, when creating the directory
   --task-name       # (Optional) use task-name to fetch the logs for --task-name
   --step-name       # (Optional) use step-name in conjunction with task-name to fetch the log for --step-name

必需的环境变量:

IBMCLOUD_API_KEY= # IBM Cloud API Token
TOOLCHAIN_REGION= # Region of the toolchain
PIPELINE_ID=      # Can be used instead of '--pipeline-id option
PIPELINE_RUN_ID=  # Can be used instead of '--pipeline-run-id option

运行命令:

$ cocoa tekton get-pipeline-logs \
   --output-dir=<output-dir> \
   --pipeline-id=<pipeline-id> \
   --pipeline-run-id=<pipeline-run-id> \
   --use-task-ref

cocoa changelog 命令

可可更改日志

不推荐使用此命令，将在 2.0.0中除去此命令。

Git Repos and Issue Tracking中不支持可可更改日志。

将存储库中两个修订版之间的更改日志打印到标准输出。

选项：

--org   # Defaults to GHE_ORG env variable, github organization
--repo  # Defaults to GHE_REPO env variable, name of the github repository

必需的环境变量:

GHE_TOKEN=  # Github Enterprise API Token (Required)
GHE_ORG=    # The owner of the repository (optional, when --org is not provided)
GHE_REPO=   # The repository name (optional, when --repo is not provided)

此命令包含三种用法:

如果同时提供了 --from 和 --to 选项，请检查范围内的落实。

选项：

--from  # git commit hash to calculate the changes from
--to    # git commit hash to calculate the changes to

运行命令:

$ cocoa changelog \
   --org=<github-organization> \
   --repo=<github-repo-name> \
   --from=<commit-hash-to-calculcate-changes-from> \
   --to=<commit-hash-to-calculate-changes-to>

包含在提供 --pr 选项时属于特定拉取请求的所有落实。

选项：

--pr # pull request number from which the changelog is calculated

运行命令:

$ cocoa changelog \
   --org=<github-organization> \
   --repo=<github-repo-name> \
   --pr=<pull-request-number>

如果未提供上述信息，那么更改日志将包含当前合并的拉取请求的更改。

运行命令:

$ cocoa changelog \
   --org=<github-organization> \
   --repo=<github-repo-name>

可可注释命令

可可评论添加

向 GitHub中的问题或拉取请求添加注释。

选项：

--content           	# (Required) The content to be added as comment to issue or pr
--id       		# (Required) The issue number or pull request number
--type             	# (Optional) The type (issue or pr), default is issue
--org               	# The git repo org
--repo              	# The git repo name
--git-provider     	# (Optional) Git service provider [github]
--git-token-path    	# (Optional) Github Token's path
--git-api-url       	# (Optional) Github API url

必需的环境变量:

GHE_ORG=                    # Can be used instead of --org (either the option or the variable is required)
GHE_REPO=                   # Can be used instead of --repo (either the option or the variable is required)

如果您使用，则需要环境变量GitHub:

GHE_TOKEN=    # Github Enterprise API Token (Optional if you are using --git-token-path)

如果要使用 github，请使用 --git-token-path 字段来设置 GitHub 令牌，并使用 --git-api-url 字段来设置 GitHub Enterprise API URL，而不是 GHE_TOKEN 和 GH_URL 环境变量。如果同时提供了环境属性和命令行参数，那么 --git-token-path 和 --git-api-url 优先。

运行命令:

$ cocoa comment add --id 1 \
                    --content "This is a test comment" \
                    --type pr \
                    --git-provider github \
                    --org <github-organization> \
	  				--repo <github-repo-name>