DevSecOps命令列介面

cocoa 檢查 pull-request-approval

在確定雜湊上檢查「取回要求」的核准狀態。 如果未核准取回要求，則會在指定的儲存庫中建立新的發生事件問題。 該指令可以識別以標籤標示的緊急取回要求，在此情況下，它的結束碼為 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

cocoa 檢查 pull-request-status

檢查給定「取回要求」的狀態及儲存庫設定。

• 分支保護: 在合併之前停用強制推送、防止刪除分支，以及選擇性地需要狀態檢查的規則。 作為增強，除了傳統的基於分支保護的驗證之外，該命令還支援基於規則集的GitHub 儲存庫驗證。 預設情況下，此指令會檢查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>

cocoa 變更-要求取得

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

cocoa 變更-要求建立

建立變更要求，並將它公佈至 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"

使用 description 選項時，指令會以新的描述取代現有的描述。 如果使用者想要附加內容到原始描述，他們需要先擷取現有的描述，並在使用此指令之前手動附加。

cocoa 變更-請求 變更-狀態-執行

透過 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

cocoa 變更-要求關閉

透過 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

cocoa 變更-要求檢查-核准

查詢變更要求的核准狀態。 如果「變更要求」是緊急狀況，則指令不會失敗，但會提示進行追溯核准。

選項：

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

cocoa 變更-要求準備

建立變更要求資料，並將它列印至主控台或檔案。

必要的環境變數:

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>

cocoa 變更-要求要求-核准

要求核准處於新狀態且未要求核准的記錄。 執行時，記錄會遵循手動核准路徑。

選項：

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

cocoa 變更-要求附件新增

將「變更」附件新增至特定的「變更要求」。

選項：

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

cocoa 變更-要求附件取得

取得變更要求的特定變更附件。

選項：

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

cocoa 變更-要求附件清單

列出變更要求的變更附件。

選項：

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

cocoa 變更-要求附件更新

更新特定變更要求中的變更附件。

選項：

--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 證明格式-摘要

將證明摘要格式化為人類可讀的格式。 它可以饋送至變更要求內容。

執行指令:

$ 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

可可證據 Markdown-摘要

將證明摘要格式化為可提供作為 GitHub 取回要求註解的 Markdown 格式。

輸入是原始摘要，可以是下列兩種格式之一:

• 摘要以 JSON 格式呈現。
• 聚集摘要，這是個別應用程式摘要的 JSON 陣列。

將聚集摘要作為輸入傳遞時，輸出會根據摘要中的應用程式來分組證明狀態。

選用旗標:

• --detailed: 如果旗標設為 true，則會產生詳細 Markdown 摘要 (依預設，對於修整的摘要，true 會設為 false )。

執行指令:

$ 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

cocoa 構件上傳

將構件上傳至指定的後端。 後端可以是不同的證明櫃類型，例如 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)

如果您正在使用 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>

CLI 選項也可以從環境變數設定，但 backend 和 upload-path 除外。

擷取藝術品

您可以使用 cocoa artifact get 指令從各種證據櫃擷取藝術品，例如 Object Storage, GitHub, 或 DevOps Insights。 這個指令允許您從不同的櫃子類型取得藝術品，每種類型都需要特定的參數。

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'

可可庫存 get-sha

從庫存儲存庫中依標籤或環境取得最新確定雜湊。 請使用 --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'

可可庫存驗證

驗證庫存儲存庫（或 JSON 檔案）中存在的條目。 庫存儲存庫可以驗證其環境（分支）或標籤（標籤）。

驗證選項包括（至少必須使用其中一個標誌）

1. 使用 --environment 標誌 - 它將分支作為值並驗證其中的所有條目。
2. 使用 --label 標誌 - 它將標籤作為值並驗證其中的所有條目。
3. 使用 --from-file 標誌 - 它接受包含庫存條目的 JSON 檔案的路徑（採用連字符格式）。

選修的：

1. 如果應使用自訂 inventoryignore 檔案名，則可以使用 --inventory-ignore-file-name 標誌來覆寫預設值。
2. 如果複製的清單儲存庫已存在且您希望命令使用相同的複製清單儲存庫，則可以使用 --inventory-path 標誌提供複製的清單儲存庫的路徑。

必要選項:

--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}"

cocoa 存貨 get-delta

從清單儲存庫取得提交之間的 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)
• Xray (選項 --type xray)
• OWASP ZAP (選項 --type owasp-zap)
• OWASP ZAP 使用者介面 (選項 --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)
• 偵測密鑰 (選項 --type detect-secrets)
• Sysdig (選項 --type sysdig)

有關Container Registry VA 和結果格式的更多信息，請參閱 Vulnerability Advisor for IBM Cloud Container Registry。 如需 CRA 漏洞掃描器的相關資訊，請參閱 配置 Code Risk Analyzer文件。

用法:

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

如果您正在使用 github，使用 --git-token-path 字段來設定您的 GitHub 令牌和 --git-api-url 欄位設定 # GitHub Enterprise API URL 而不是 GHE_TOKEN 和 GH_URL 環境變數。 如果同時提供兩者，則 --git-token-path 和 --git-api-url 優先。

回覆值：

• 如果找不到任何問題，或所有找到的問題都已設定「豁免」或「寬限期」，則指令會以零狀態結束。
• 如果發現任何問題未設定「豁免」或「寬限期」，則指令會以非零狀態結束。
• 如果格式 == 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 旗標，則指令會使用與現行執行相同的工具、主旨及突發事件 ID 來搜尋未解決的問題。 如果發現任何問題，當 --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 旗標，將更多詳細資料新增至資產。

您可以使用接受 key=value 配對的 --origin 旗標，來提供資產來源的更多詳細資料。

系統會自動挑選部分環境變數，以新增資產來源的相關詳細資料:

• 設定 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 旗標來新增相關資產 (對於多個相關資產，可以多次指定該旗標)。 資產可以使用其內部 ID 或其 URI 來指定。 所有相關的資產 ID（整個樹直到第一個資產）都會新增到資產 json 中的 parents 欄位。

依預設，id 格式 ( --format 旗標) 會列印所建立資產的內部 ID。 使用 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%

可可鎖資產取得 < 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

可可櫃證據新增

將證據新增至證據櫃。

您可以使用旗標來指定證明櫃。 如需相關資訊，請參閱 可可櫃指令。

證據可以使用下列旗標來設定：

• --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 或內部 ID) 與證明相關，請參閱 cocoa locker asset 指令。 旗標可以指定多次。 資產必須已存在於櫃中。
• --attachment: 指定證明的檔案附件。 每一個附件都必須指向現有的檔案，且每一個附件名稱都必須是唯一的 (亦即，不允許 --attachment a/foo.json --attachment b/foo.json )。
• --attachment-url: 指定已儲存在證明櫃中的附件 URL。 每個 URL 必須指向唯一的配件，確保不重複。 此旗標可以指定多次，以包含多個 URL。
• --issue: 問題 URL 清單，可用來追蹤發現項目相關的活動。 旗標可以多次傳遞。
• --findings-path: 使用此路徑來傳遞 JSON 發現項目陣列，這是「發生事件」處理程序指令的輸出。
• --scope: 可用來使多個來源的證明產生關聯的唯一 ID。
• --comment-on-issues: 使用 --issue 旗標將包含所建立證明的詳細資料的註解新增至所提供的突發事件問題
  • 由於問題可以在 github 上，因此會從問題 URL 剖析提供者
  • 每個問題都必須來自相同的儲存庫
  • 問題 URL 必須符合下列型樣:
    • https://<host>/<owner>/<name>/issues/<issue number>-適用於 github
  • 存取問題儲存庫所需的環境變數:
    • 如果 URL 指向 github 問題:
      • GH_URL: 選用，預設為 https://<region>.git.cloud.ibm.com/api/v4
      • GHE_TOKEN

證明 JSON 中附件的標籤資訊:

證明 JSON 中的每一個附件區段都有一個標籤內容，用來保留附件的相關 meta 資料。 預設值會指派給標籤，且此值視附件輸入是檔案路徑還是附件-URL 而定。 在附件路徑或附件 URL 尾端新增 ::label=<value>，以傳遞自訂標籤。

範例：

• --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: 類似於 dry-run。 實際上不會將證據新增至儲物櫃，但會將附件 (如果有的話) 新增至儲物櫃。 顯示將新增的證明。
• --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

可可儲物櫃證據取得 <證據編號>

從櫃中擷取一段證明。

選項：

--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 證明附加至摘要。
  • 請參閱 cocoa locker，以瞭解如何配置 Cloud Object Storage 儲存區。
• --dry-run: 與 --check-immutable-storage 結合時具有作用。 如果使用的話，com.ibm.immutable_storage 證明只會附加至摘要，但不會上傳至證明櫃。
• --clone-dir：可選參數，用於確定 Evidence Repository 的克隆路徑，預設會克隆 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 天。

如需相關資訊，請參閱 可可櫃指令。

必要的環境變數:

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"

cocoa tekton 取得管道日誌

從管線執行建立每個步驟的日誌檔，並將它儲存至目錄。 使用環境變數 (PIPELINE_ID、PIPELINE_RUN_ID) 或以明確旗標 (--pipeline-id、--pipeline-run-id) 置換環境變數。透過提供 --task-name 及 --step-name 旗標，也可以在每個作業及每個步驟層次上擷取日誌檔。

如果提供 --task-name，則指令會嘗試取回並為給定作業名稱的每個步驟建立日誌檔。

如果隨 --task-name 一起提供 --step-name，則指令會針對所提供的 task-name 建立特定步驟的日誌檔。沒有 --task-name 的 --step-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 註解新增

在 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 手 --git-api-url 選項優先。

範例：向拉取請求新增標籤

您可以透過執行以下命令向拉取請求新增標籤：

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