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

检查落实散列上的拉取请求的核准状态。 如果未核准拉取请求，那么将在指定的存储库中创建新的事件问题。 该命令可以识别标有标签的紧急拉取请求，在这种情况下，它的退出代码为 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 Enterprise API URL，以此替代 GHE_TOKEN 和 GH_URL 环境变量。 如果同时提供了这两个值，那么 --git-token-path 和 --git-api-url 优先。

运行命令:

cocoa check pull-request-approval

可可检查拉取请求状态

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

• 分支保护: 用于禁用强制推送，阻止删除分支以及 (可选) 在合并之前需要状态检查的规则。 作为一项增强功能，除了传统的基于分支保护的验证外，该命令还支持 GitHub Repositories 的基于规则集的验证。 默认情况下，该命令会检查GitHub 存储库中分支上的关联规则集，如果没有找到规则集，则回退到基于传统分支保护的验证。 如果某个分支同时存在规则集和传统分支保护规则，则命令只考虑规则集。 有关 GitHub Rulesets 的更多信息，请参阅 配置 GitHub 资源库
• 落实状态检查: 用于标记具有 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 Enterprise API URL，以此替代 GHE_TOKEN 和 GH_URL 环境变量。 如果同时提供了 GHE_TOKEN GH_URL 和 --git-token-path --git-api-url 对，那么 --git-token-path 和 --git-api-url 优先。

要指定分支保护设置的输出文件路径，请使用 "--branch-protection-settings-output-path 选项。 当分支受到保护时，版本库分支保护设置的 JSON 表示形式将保存在此指定路径中。

要指定分支保护验证结果的输出文件路径，请使用 "--branch-protection-markdown-output-path 选项。 当分支受到保护时，验证结果将以Markdown格式保存在此指定路径中。

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 check pull-request-status \
    --branch-protection-settings-output-path <path/to/file> \
    --branch-protection-markdown-output-path <path/to/file>

可可更改-请求获取

从 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 v3 API 更新现有的变更请求，并将其打印到控制台。

ServiceNow v3:

SERVICENOW_URL=       # ServiceNow API URL
CHANGE_REQUEST_ID=    # ID of the Change Request

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

选项：

--close-notes                    # (Optional) Any pertinent notes to add to change request closure.
--close-category                 # (Optional) Change request close notes (choices:  'successful', 'successful_issues', 'unsuccessful', 'cancelled')
--description                    # (Optional) Description of the change

运行命令:

# Update Change Request with sample close-notes, close category and description.
$ cocoa change-request update --close-notes="sample close-note" --close-category="successful" --description="sample change description"

使用描述选项时，命令会用新描述替换现有描述。 如果用户想在原始描述中添加内容，则需要提取现有描述并手动添加，然后再使用此命令。

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

通过 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>"

可可更改-请求附件添加

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

选项：

--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>'

可可更改请求评论添加

为特定变更请求添加注释。

选项：

--comment          # Comment to add [string] [required]
--provider         # (Optional) Change Management service provider (choices: 'servicenow-v3', 'gitlab', 'github-enterprise', default: 'servicenow-v3')
--git-api-url      # (Optional) Git API URL [string]
--git-token-path   # (Optional) Git token path to read the secret from [string]

必需的环境变量 (如果您正在使用 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

GitLab 提供商所需的环境变量：

GITLAB_TOKEN=    # Gitlab Token
GITLAB_URL=      # Gitlab API URL
GITLAB_ORG=      # Gitlab ORG
GITLAB_REPO=     # Gitlab REPO Name

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

GHE_TOKEN=                        # Github Enterprise API Token
GITHUB_CHANGE_MANAGEMENT_ORG=     # The owner of the repository
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name

运行命令:

$ cocoa change-request comment add "CHGXXXXXXX" \
        --comment='This is a comment for the change request'
$ cocoa change-request comment add "CHGXXXXXXX" \
        --comment='Adding comment using GitLab provider' \
        --provider='gitlab'

可可更改请求评论列表

列出特定变更请求的所有注释。

选项：

--provider         # (Optional) Change Management service provider (choices: 'servicenow-v3', 'gitlab', 'github-enterprise', default: 'servicenow-v3')
--git-api-url      # (Optional) Git API URL [string]
--git-token-path   # (Optional) Git token path to read the secret from [string]
--last             # (Optional) Retrieve only the last n comments [number]
--before           # (Optional) Filter comments created before this date (ISO 8601 format, e.g., YYYY-MM-DDTHH:MM:SSZ) [string]
--after            # (Optional) Filter comments created after this date (ISO 8601 format, e.g., YYYY-MM-DDTHH:MM:SSZ) [string]

请注意：

• --last 参数必须是非负数。
• --before 和 --after 参数接受 ISO 8601 格式的日期，不能是未来日期。
• 同时使用 --before 和 --after 时，--before 日期必须大于 --after 日期。
• 过滤器按以下顺序应用：先应用日期过滤器（--before, --after ），然后应用 --last 来限制结果。

必需的环境变量 (如果您正在使用 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

GitLab 提供商所需的环境变量：

GITLAB_TOKEN=    # Gitlab Token
GITLAB_URL=      # Gitlab API URL
GITLAB_ORG=      # Gitlab ORG
GITLAB_REPO=     # Gitlab REPO Name

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

GHE_TOKEN=                        # Github Enterprise API Token
GITHUB_CHANGE_MANAGEMENT_ORG=     # The owner of the repository
GITHUB_CHANGE_MANAGEMENT_REPO=    # The repository name

运行命令:

# List all comments for a change request
$ cocoa change-request comment list "CHGXXXXXXX"
# List comments using GitHub Enterprise provider
$ cocoa change-request comment list "CHGXXXXXXX" --provider='github-enterprise'
# Get only the last 5 comments
$ cocoa change-request comment list "CHGXXXXXXX" --last=5
# Get comments created before a specific date
$ cocoa change-request comment list "CHGXXXXXXX" --before="2026-03-20T10:00:00Z"
# Get comments created after a specific date
$ cocoa change-request comment list "CHGXXXXXXX" --after="2026-03-15T08:00:00Z"
# Get comments within a date range
$ cocoa change-request comment list "CHGXXXXXXX" --after="2026-03-15T08:00:00Z" --before="2026-03-20T10:00:00Z"
# Get the last 10 comments within a date range
$ cocoa change-request comment list "CHGXXXXXXX" --after="2026-03-15T08:00:00Z" --before="2026-03-20T10:00:00Z" --last=10

可可证据格式-摘要

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

运行命令:

$ 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格式）。
• 聚集摘要，这是单个应用程序摘要的 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。 不同的储物柜需要提供不同的参数。

选项：

--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)

如果您使用的是 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 优先。

运行命令:

$ 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 选项。

找回神器

您可以使用 cocoa artifact get 命令从各种证据存储库（例如 Object Storage、GitHub, ）中检索证据。 此命令允许您从不同类型的储物柜中取出物品，每种储物柜都有特定的参数要求。

cocoa artifact get 命令从指定的后端检索一个工件。 不同的储物柜需要提供不同的参数。 选项：

--backend           # Specifies the types of locker to retrieve the artifact from ('cos', 'git')
--artifact-prefix   # Path where the artifact is present. To be used in COS only, not available in Git. (Use this or --artifact-path, can't be used together)
--artifact-path     # Absolute path on where the artifact is present.
--is-summary        # If present, this returns the merged summary from all the file paths.

Git的选项:

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

必需的环境变量:

必需的环境变量 (如果使用的是 "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)
BACKUP_COS_API_KEY=        # Cloud Object Storage API Key (Required while migrating from one COS bucket to another to read the old artifacts)
BACKUP_COS_BUCKET_NAME=    # Bucket Name where the artifact will be uploaded in the COS Instance (Required while migrating from one COS bucket to another to read the old artifacts)
BACKUP_COS_ENDPOINT=       # The COS API Endpoint matching the region where the bucket is located (Required while migrating from one COS bucket to another to read the old artifacts)

如果您使用的是 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 优先。

运行命令:

$ cocoa artifact get
$ cocoa artifact get \
  --backend=[choices: "git", "cos"] \ # e.g. --backend=cos
  --artifact-path <file-path> \ # full path in case of git, cos can utilise --artifact-prefix <file-path>

CLI选项也可以通过环境变量进行设置，但 backend 和 artifact-path / artifact-prefix 除外。

可可库存加

向库存存储库添加值。 使用 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

运行命令:

$ cocoa inventory add \
  --artifact=us.icr.io/namespace/hello-compliance-app:20201217081811-master-b85e3d472e9cc35b429c39e8c3f9eb282738c20a@sha256:da36831d5154307ac9ca4b8d900df2da0c6c14754977c32479dc62994b5722d0 \
  --type=image \
  --sha256=sha256:786800e8e48938664fe2397ca14ab8dabd48f34656ef5cfda4143b4519cb714f \
  --name=hello-compliance-app \
  --repository-url=https://github.com/test-org/compliance-app-20201211 \
  --commit-sha=8e86dc4647ce28632103dce46b756c70d339349a \
  --version=v4 \
  --build-number=33 \
  --pipeline-run-id=f21321af-9084-4af3-80b8-4fb34143b7d9 \
  --git-token-path=./git-token \
  --org=test-org \
  --app-artifacts='{"app": "test", "some_value": "value"}' \
  --repo=compliance-inventory-repo
  --signature=owFNUX1IE3EY3vwAEy0VyoSJdkVWtu0+d3eTjNIIi0jETCSU3353cz+83V23myi2BlFgYiUFqSmZLciUzCJkRYJp9IEWFWXB0hAyrBQxEjIIuhFSf70vL8/7vM/zPi3JsaYEc+TnbqG8qrnTPDZ8w2WqiqwtacCghnQEgYQ5GzAkiLKO9PpoLyiwRtSsmugWNVGGIubE/D4bgpoNKXag60gCdo8oSYoVKl5VQsDAWIGqOkmcxAmSYHGO4AjC6gU+3eBxcYxICTRLijyEFOOiSR5SvMhBys2LLpIjWYqDJA6wwHYMeUG1+J8GL5CRW/TpVgFVG8VQ4vMAknE4BUA5OIoQGIKhKZwFkIeAdnECj+OCmxQADh2QoFmG5lkWUiTN8gJ0kDxPuxiWJAU8ekyvV6PegK54EcyGiqwDJItatg9Vy0D3a2IUpKg6UuS/T4KaaIC1fzuMDbfhmMGEvIY64FUxJ+Ew3PMU5SADgdNmKs5kTjBlrtsQ99iyY49nns8o6jsXWgkjPiYahClxVcrK5Flngumz2j7YdmD0ecutytsvxxNPHflKlRV2RyqD69NjC6Smji9XuukFyZ+lvM18gUr7F4NXge9YyZPik411tc1n9bKO/hDz7oGaX/ur94OnNHiwOG6n5ZsrsCsvtyvmkH4zOWlrRWuL7fzgj9zlcCTAhtu2LbeGLNfv3Ju0Jc9PZPk7Pm3Ov2CW+2xj8ReX6ooGamZ610yqRM/+8Qo2XnOeyZzbVKgs+f2+9unpJOve4Tmla+PdqftDWkHPm9Vq3nsyZ2DUkmP/nTb7qNw5l2SfWtiSemJx9nLaYOpx6amlOT18aeIwJQhHg1XOjJF9r18NXQvPuL9rH5tSQqbGhyN/AA== \
  --location=stage#stage-us.icr.io/namespace/hello-compliance-app:20201217081811-master-b85e3d472e9cc35b429c39e8c3f9eb282738c20a@sha256:da36831d5154307ac9ca4b8d900df2da0c6c14754977c32479dc62994b5722d0

$ cocoa inventory add \
  --environment=staging \
  --artifact=foo-helm-chart/foo/chart.yaml \
  --repository-url=https://github.com/test-org/compliance-app-20201211 \
  --provenance=https://github.com/test-org/compliance-app-20201211/foo-helm-chart/foo/chart.yaml \
  --commit-sha=786800e8e48938664fe2397ca14ab8dabd48f34656ef5cfda4143b4519cb714f \
  --build-number=33 \
  --pipeline-run-id=f21321af-9084-4af3-80b8-4fb34143b7d9 \
  --version=v4 \
  --name=foo-app-helm-chart \
  --sha256=sha256:9106cdf8c0f5c110f1cdf65825edd195927cdb439db8767791ac2011c2d41894 \
  --signature=9106cdf8c0f5c110f1cdf65825edd195927cdb439db8767791ac2011c2d41894 \
  --type=helm-chart

$ cocoa inventory add --from-file multi-artifacts.json \
  --environment=environment  \
  --org=test \
  --repo=repository

[
  {
    "artifact": "us.icr.io/namespace/hello-compliance-app:20201217081811-master-b85e3d472e9cc35b429c39e8c3f9eb282738c20a@sha256:da36831d5154307ac9ca4b8d900df2da0c6c14754977c32479dc62994b5722d0",
    "type": "image",
    "sha256": "sha256:786800e8e48938664fe2397ca14ab8dabd48f34656ef5cfda4143b4519cb714f",
    "name": "hello-compliance-app",
    "repository-url": "https://github.com/test-org/compliance-app-20201211",
    "commit-sha": "8e86dc4647ce28632103dce46b756c70d339349a",
    "version": "v4",
    "build-number": 33,
    "pipeline-run-id": "f21321af-9084-4af3-80b8-4fb34143b7d9",
    "provenance": "us.icr.io/namespace/hello-compliance-app:20201217081811-master-b85e3d472e9cc35b429c39e8c3f9eb282738c20a@sha256:da36831d5154307ac9ca4b8d900df2da0c6c14754977c32479dc62994b5722d0",
    "signature": "owFNUX1IE3EY3vwAEy0VyoSJdkVWtu0+d3eTjNIIi0jETCSU3353cz+83V23myi2BlFgYiUFqSmZLciUzCJkRYJp9IEWFWXB0hAyrBQxEjIIuhFSf70vL8/7vM/zPi3JsaYEc+TnbqG8qrnTPDZ8w2WqiqwtacCghnQEgYQ5GzAkiLKO9PpoLyiwRtSsmugWNVGGIubE/D4bgpoNKXag60gCdo8oSYoVKl5VQsDAWIGqOkmcxAmSYHGO4AjC6gU+3eBxcYxICTRLijyEFOOiSR5SvMhBys2LLpIjWYqDJA6wwHYMeUG1+J8GL5CRW/TpVgFVG8VQ4vMAknE4BUA5OIoQGIKhKZwFkIeAdnECj+OCmxQADh2QoFmG5lkWUiTN8gJ0kDxPuxiWJAU8ekyvV6PegK54EcyGiqwDJItatg9Vy0D3a2IUpKg6UuS/T4KaaIC1fzuMDbfhmMGEvIY64FUxJ+Ew3PMU5SADgdNmKs5kTjBlrtsQ99iyY49nns8o6jsXWgkjPiYahClxVcrK5Flngumz2j7YdmD0ecutytsvxxNPHflKlRV2RyqD69NjC6Smji9XuukFyZ+lvM18gUr7F4NXge9YyZPik411tc1n9bKO/hDz7oGaX/ur94OnNHiwOG6n5ZsrsCsvtyvmkH4zOWlrRWuL7fzgj9zlcCTAhtu2LbeGLNfv3Ju0Jc9PZPk7Pm3Ov2CW+2xj8ReX6ooGamZ610yqRM/+8Qo2XnOeyZzbVKgs+f2+9unpJOve4Tmla+PdqftDWkHPm9Vq3nsyZ2DUkmP/nTb7qNw5l2SfWtiSemJx9nLaYOpx6amlOT18aeIwJQhHg1XOjJF9r18NXQvPuL9rH5tSQqbGhyN/AA==",
    "app-artifacts": "{\"app\": \"test\", \"some_value\": \"value\"}",
    "locations": {
      "stage":"stage-us.icr.io/namespace/hello-compliance-app:20201217081811-master-b85e3d472e9cc35b429c39e8c3f9eb282738c20a@sha256:da36831d5154307ac9ca4b8d900df2da0c6c14754977c32479dc62994b5722d0",
      "prod":"prod-us.icr.io/namespace/hello-compliance-app:20201217081811-master-b85e3d472e9cc35b429c39e8c3f9eb282738c20a@sha256:da36831d5154307ac9ca4b8d900df2da0c6c14754977c32479dc62994b5722d0"
   }
  },
  {
    "artifact": "foo-helm-chart/foo/chart.yaml",
    "repository-url": "https://github.com/test-org/compliance-app-20201211",
    "provenance": "https://github.com/test-org/compliance-app-20201211/foo-helm-chart/foo/chart.yaml",
    "commit-sha": "786800e8e48938664fe2397ca14ab8dabd48f34656ef5cfda4143b4519cb714f",
    "build-number": 34,
    "pipeline-run-id": "f21321af-9084-4af3-80b8-4fb34143b7d9",
    "version": "v4",
    "name": "foo-app-helm-chart",
    "sha256": "sha256:9106cdf8c0f5c110f1cdf65825edd195927cdb439db8767791ac2011c2d41894",
    "signature": "9106cdf8c0f5c110f1cdf65825edd195927cdb439db8767791ac2011c2d41894",
    "type": "helm-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

如果您使用的是 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 使用其内部高速缓存来查找证据 (速度更快)，但结果可能是过时的。

运行命令:

# 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 ( not required for deleting a cocoa inventory label)
--to-label     # Another label in the inventory that can be referenced or removed. ( not required for deleting a cocoa inventory label )

必需的环境变量:

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

如果您使用的是 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 优先。

运行命令:

# 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 `label-to-move` 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"

# delete the `label-to-delete` label from the inventory
$ cocoa inventory label delete \
  --org='Github-ID' \
  --repo='compliance-inventory-repo' \
  "label-to-delete"

促进可可盘存

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

必需的环境变量:

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

如果您使用的是 github，请在 --git-token-path 字段中设置您的 GitHub 令牌，并在 --git-api-url 字段中设置 GitHub Enterprise API URL，而不是使用环境变量 GHE_TOKEN 和 GH_URL。 如果同时提供了这两个值，那么 --git-token-path 和 --git-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'

可可库存验证

验证清单 repo（或 JSON 文件）中的条目。 清单 repo 可以验证其环境（分支）或标签（标记）。

需要验证的选项包括（必须使用至少一个标记）

1. 使用 "--environment 标志--它以分支为值，并验证其中的所有条目。
2. 使用 "--label 标记--该标记将标签作为值，并验证其中的所有条目。
3. 使用 "--from-file 标志--该标志接收包含清单条目的 JSON 文件路径（连字符格式）。

Optional:

1. 如果要使用自定义的清单忽略文件名，可以使用 "--inventory-ignore-file-name 标记来覆盖默认值。
2. 如果已经存在克隆的清单 repo，并且希望命令使用相同的清单 repo，可以使用 "--inventory-path 标记提供克隆清单 repo 的路径。

必需选项:

--org          # The Github organisation which owns the inventory repository.
--repo         # The name of the inventory repository.
--environment  # The inventory branch to validate
--label        # label in the inventory, that will be validated

环境变量（可选，可用于代替提供--org --repo和--git-token-path)：

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)
GHE_TOKEN=    # Github Enterprise API Token (Optional if using --git-token-path)

运行命令:

$ cocoa inventory validate \
   --org "Github-ID" \
   --repo "inventory-repo" \
   --git-token-path="$INVENTORY_TOKEN_PATH" \
   --label "$latest_tag" \
   --inventory-path "${DIRECTORY_NAME}"

可可库存

从清单版本库中获取两次提交之间的 delta 值。 可选择获取两个提交之间 delta 范围内的同行评审提交。

必需的环境变量:

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

运行命令:

$ cocoa inventory get-delta \
  --git-provider=github \
  --git-token-path=./git-token \
  --org=test-org \
  --repo=compliance-inventory-repo \
  --git-api-url=<git-api-url> \
  --to-sha 534ff2bbbf0291e10f3b1f6aa409d8de059bbe27 \
  --from-sha e54b5aa12ccb687020ac04b16d489b5a04f90399 \
  --inventory-ignore-file-path=/path/to/current/.inventoryignore \
  --previous-inventory-ignore-file-path=/path/to/previous/.inventoryignore \
  --delta \
  --delta-deletion \
  --inventory-list \
  --peer-review

可可库存更新-地点

更新清单存储库中的条目/工件位置。

必需的环境变量:

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

运行命令:

$ cocoa inventory update-locations \
  --name=hello-compliance-app \
  --git-token-path=./git-token \
  --org=test-org \
  --repo=compliance-inventory-repo \
  --location=stage#stage-us.icr.io/namespace/hello-compliance-app:20201217081811-master-b85e3d472e9cc35b429c39e8c3f9eb282738c20a@sha256:da36831d5154307ac9ca4b8d900df2da0c6c14754977c32479dc62994b5722d0 \
  --location=prod#prod-us.icr.io/namespace/hello-compliance-app:20201217081811-master-b85e3d472e9cc35b429c39e8c3f9eb282738c20a@sha256:da36831d5154307ac9ca4b8d900df2da0c6c14754977c32479dc62994b5722d0

可可事件进程

此命令处理提供的扫描结果，并根据每个漏洞在指定存储库中创建事件问题。 如果已存在主题/事件对的问题，那么不会创建新的问题。

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

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

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

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

• Container Registry VA 扫描 (选项 --type va)
• CRA 漏洞扫描 (选项 --type cra)
• CRA CIS 扫描（选项 --type cra-cis ）
• Xray (选项 --type xray)
• OWASP ZAP (选项 --type owasp-zap)
• OWASP ZAP UI (选项 --type owasp-zap-ui)
• Twistlock (选项 --type twistlock)
• 容器镜像多扫描器（CIMS）扫描（选项 --type cims ）
• 同级复审扫描 (选项 --type peer-review)
• GoLang 安全扫描 (选项 --type gosec)
• SonarQube 扫描 (选项 --type sonarqube)
• 修补扫描 (选项 --type mend)
• 修复 SAST 扫描（选项 --type mend-sast ）
• Checkov (选项 --type checkov)
• 针对 Terraform 的 CRA 漏洞扫描 (选项 --type cra-tf)
• Terraform 安全扫描 (选项 --type tfsec)
• Fips 扫描程序 (选项 --type fips-scanner)
• 检测私钥 (选项 --type detect-secrets)
• Sysdig (选项 --type sysdig)
• CycloneDX (选项 --type cyclonedx)
• Grype（选项 --type grype ）

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

用法：

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

选项：

--type             # (Required) Scan type [choices: "cra", "va", "xray", "peer-review", "gosec","owasp-zap", "owasp-zap-ui", "sonarqube", "twistlock", "cims", "mend","mend-sast", "checkov", "cra-tf", "tfsec", "fips-scanner", "contrast-sast","detect-secrets", "sysdig", "cyclonedx", "grype", "cra-cis"]
--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)

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

返回值：

• 如果未找到任何问题，或者所有发现的问题都设置了“豁免”或 "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://<region>.git.cloud.ibm.com/api/v4 ），而不是 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

可可储物柜资产添加 < URI >

将资产添加到证据锁定程序。 如果存在指定的资产，它将显示资产信息。

选项：

--type             # Type of the asset ( All types are supported )
--version          # Show version number
--format           # Output format ("id", "json", default: "id")
--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 必须在以下模式上匹配:

• 对于 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.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.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 资产获取 < URI >

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

选项：

--type             # Type of the asset
--version          # Show version number
--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": <repository-url>,
    "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": <repository-url>,
    "tag": "v1.2.3"
   },
   "date": "2021-07-15T14:26:06.301Z",
   "type": "image",
   "related": [],
   "parents": ["b5bbbbb55555b5555b555b55b5555bb5b555b5b555bb5b55bbb5555fbbbbb"]
}

 cocoa locker asset get https://github.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": <repository-url>,
    "tag": "v1.2.3"
   },
   "date": "2021-07-15T14:26:06.301Z",
   "type": "image",
   "related": [],
   "parents": []
}

可可储物柜资产摘要获取 < 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.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee \
  --scope 11a1aa11-1a11-11a1-aa11-a11a1a1111a1 \
  --environment prod \
  --service-environment prod

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

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

可可储物柜资产列表 < URI >

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

选项：

--type             # Type of the asset
--version          # Show version number
--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.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://<region>.git.cloud.ibm.com/api/v4
      • 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.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.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee
                            --attachment path/to/results/junit.xml \
                            --issue <issue-link> \
                            --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.com/foo/bar/blob/master/raw/attachments/5aa5555aa55aa55a555aa5a5aa555555aaaa5aa5aa5555a55a5aa5aa5a5aaaaa/content
                            --asset https://github.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.com/foo/bar.git#aaaaaaaabbbbbbbbccccccccddddddddeeeeeeee
                            --issue <issue-link> \
                            --findings-path <path/to/file> \
                            --attachment path/to/results/junit.xml::label=unit-test

可可储物柜证据获取 <证据ID>

从锁定程序中检索证据。

选项：

--version          # Show version number
--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": <git-uri-to-asset>,
       "url": "https://s3.us-south.cloud-object-storage.appdomain.cloud/cocoa-development/assets/7d930918fbb8be80f3a5100f0313c5b2518eba22cc915194cf971d4daf5170be/index.json"
     }
   ]
}

可可储物柜证据摘要 < 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-id >

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

选项：

--version          # Show version number

运行命令以上载附件:

$ 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.
--output-config-path # optional path to create a more suitable file based on the current config file

运行命令：

 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>`

可可储物柜证据收集

收集证据并存放在储物柜中。 该命令是 collect-evidence shell 脚本的底层实现。

cocoa locker evidence collect [OPTIONS]

cocoa locker evidence collect \
  --tool-type "sonarqube" \
  --evidence-type "com.ibm.static_scan" \
  --assets "app-repo:repo" \
  --status "success" \
  --attachment ./sonarqube-result.json \
  --pipeline-run-id "abc123" \
  --pipeline-namespace "ci" \
  --incident-org "my-org" \
  --incident-repo "compliance-issues" \
  --meta "environment=staging"

可可储物柜证据再利用

查找并重复使用特定资产的现有证据。 该命令是 check-evidence-for-reuse shell 脚本的底层实现。

cocoa locker evidence reuse [OPTIONS]

cocoa locker evidence reuse \
  --tool-type "sonarqube" \
  --evidence-type "com.ibm.static_scan" \
  --assets "app-repo:repo" \
  --pipeline-run-id "abc123" \
  --pipeline-namespace "ci" \
  --incident-org "my-org" \
  --incident-repo "compliance-issues" \
  --format "json"

cocoa locker evidence reuse \
  --tool-type "cra" \
  --evidence-type "com.ibm.code_vulnerability_scan" \
  --assets "app-repo:repo" \
  --pipeline-run-id "xyz789" \
  --pipeline-namespace "ci" \
  --incident-org "my-org" \
  --incident-repo "compliance-issues" \
  --evidence-validity-period 48 \
  --meta "tool-version=1.2.3" \
  --meta "base-image=ubuntu:22.04" \
  --format "json"

cocoa locker evidence reuse \
  --tool-type "owasp-zap" \
  --evidence-type "com.ibm.dynamic_scan" \
  --assets "my-app:artifact" \
  --pipeline-run-id "xxx-001" \
  --pipeline-namespace "cd" \
  --incident-org "my-org" \
  --incident-repo "compliance-issues" \
  --evidence-reuse-for-failure \
  --format "json"

可可特克顿 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

可可评论添加

向 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>

添加可可标签

为 GitHub 或 GitLab 中的拉取请求添加一个或多个标签。

选项：

--label           	# (Required) The label to be added to the pull request. This command be specified multiple times.
--id       	        # (Required) The pull request number. Can be specified multiple times.
--type             	# (Optional)The type of the item (issue or PR). The default type is PR.
--org               # The Git repository organization.
--repo              # The Git repository name.
--git-provider     	# (Optional) The Git service provider. The default git provider is Github.
--git-token-path    # (Optional) The path to the Git token.
--git-api-url       # (Optional) The URL of the Git API.

必需的环境变量:

GHE_ORG=                    # The Git repository organization. Can be used instead of the --org option. Either the option or the variable is required.
GHE_REPO=                   # The Git repository name. Can be used instead of the --repo option. 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-pat h 和 --git-api-url 选项优先。

示例：为拉动请求添加标签

您可以通过运行以下命令为拉动请求添加标签：

$ cocoa label add --id 1 \
                  --label "deployed" \
                  --type pr \
                  --git-provider github \
                  --org <github-organization> \
                  --repo <github-repo-name>