Docker イメージを構成するには、プロジェクトの GitLab インスタンスで次の環境変数が使用可能である必要があります。

• SNOW_TOKEN：ServiceNow トークン番号。これはマスクされた変数であり、ジョブには表示されません。
• SNOW_TOOLID：ServiceNow ツール ID。
• SNOW_URL：ServiceNow インスタンスの URL。

GitLab プロジェクトを構成すると、プロジェクトの環境変数が作成され、最後に構成された変数値が考慮されます。アップグレードのお客様は、既存の GitLab プロジェクトを再構成するか、GitLab インスタンスに環境変数を手動で追加する必要があります。変数の追加については、GitLab のドキュメントを参照してください。

GitHub Actionsインスタンスで次の環境変数を設定する必要があります。

• SNOW_TOKEN：ServiceNow トークン番号。これはマスクされた変数であり、ジョブには表示されません。
• SNOW_TOOLID：ServiceNow ツール ID。
• SNOW_URL：ServiceNow インスタンスの URL。

GitHub アクションパイプラインでは、次の環境変数を渡す必要があります。

• PIPELINE_ID:リポジトリのワークフロー実行 ID。使用状況 - PIPELINE_ID:${{github.run_id }}
• API_V4_URL:GitHub サーバーの URL。使用状況 - API_V4_URL:${{ github.server_url }}
• JOB_ID:リポジトリのワークフロー実行 ID。使用状況:PIPELINE_ID:${{ github.run_id }}
• PROJECT_PATH:ワークフローの名前。使用法 - PROJECT_PATH:${{ github.repository }}/${{github.workflow}}
• REPOSITORY_NAME:リポジトリの名前。使用法 - REPOSITORY_NAME: ${{ github.repository }}
• RUN_ATTEMPT:ワークフローの試行回数。使用状況 - RUN_ATTEMPT:${{ github.run_attempt }}
• PROJECT_TITLE:ワークフローの名前。使用法 - PROJECT_TITLE:${{ github.repository }}/${{github.workflow}}
• COMMIT_BRANCH:ワークフローが実行されている分岐の名前。使用状況 - COMMIT_BRANCH:${{ github.ref_name }}
• WORKFLOW_NAME:ワークフローの名前。使用法 - WORKFLOW_NAME:${{ github.workflow }}

リポジトリを設定すると、リポジトリの環境変数が作成され、最後に設定された変数値が考慮されます。アップグレードのお客様は、既存のリポジトリを再構成するか、インスタンスの環境変数を手動で追加する必要があります。

次の環境変数は、Harness インスタンスで構成する必要があります。

• SNOW_TOKEN：ServiceNow トークン番号。これはマスクされた変数であり、ジョブには表示されません。
• SNOW_TOOLID：ServiceNow ツール ID。
• SNOW_URL：ServiceNow インスタンスの URL。

• HARNESS_STAGE_NAME: "<+stage.identifier>"

• HARNESS_PIPELINE_NAME: "<+org.identifier>/<+project.identifier>/<+pipeline.name>"

リポジトリを設定すると、リポジトリの環境変数が作成され、最後に設定された変数値が考慮されます。アップグレードのお客様は、既存のリポジトリを再構成するか、インスタンスの環境変数を手動で追加する必要があります。

パイプラインにカスタムアクションを追加する前に、パイプラインで ServiceNow Docker イメージ (servicenowdocker/sndevops:6.2.0) を渡す必要があります。https://github.com/ServiceNow/app-devops-gitlab にある app-devops-gitlab パブリックリポジトリのクローンを作成し、次のコマンドを実行して Docker イメージを作成できます。

docker build -t servicenowdocker/sndevops:6.2.0

docker push servicenowdocker/sndevops:6.2.0

Docker イメージは、.ymlファイルの先頭に追加できます。ジョブごとに個別に追加する必要はありません。

プロキシをサポートするために次の環境変数を設定します。

• PROXY_ENDPOINT:# 例:http://localhost:7080 や https://proxy.example.com:8080
• PROXY_USERNAME:# オプション:プロキシ認証用
• PROXY_PASSWORD:# オプション:プロキシ認証用
• PROXY_AUTH: # オプション:API キーを使用した代替認証

PROXY_ENDPOINTは HTTP または HTTPS のいずれかです。下位互換性のために、HTTP_PROXYとHTTPS_PROXYもサポートされています。HTTPS プロキシで自己署名証明書を使用している場合は、NODE_TLS_REJECT_UNAUTHORIZED=0 (テストのみ) に設定します。認証は、次の方法で提供できます。

• ユーザー名/パスワード:PROXY_USERNAMEとPROXY_PASSWORDを使用します
• API キー:PROXY_AUTHを使用
• 認証なし:認証変数は未設定のままにします

例：

stages:
  - package

package:
  stage: package
  image: servicenowdocker/sndevops:6.2.0
  variables:
    PROXY_ENDPOINT: "https://proxy.example.com:8080"
    PROXY_USERNAME: "proxy_user"
    PROXY_PASSWORD: "proxy_pass"
  script: 
    - sndevopscli create package -n "package-name" -a '[{"name":"artifact-name","repositoryName":"artifact-repo-name","version":"1.3.0"}]'

ServiceNow DevOps 変更カスタムステップをジョブレベルで追加して、ServiceNowインスタンスに変更を作成します。例：

stages:
  - DevOpsChangeApproval

ServiceNow DevOps Change:
  stage: DevOpsChangeApproval
  image: servicenowdocker/sndevops:6.2.0
  script: 
    - sndevopscli create change -p "{\"changeStepDetails\":{\"timeout\":3600,\"interval\":100},\"attributes\":{\"short_description\":\"Software Deployment\",\"description\":\"Software Deployment.\",\"assignment_group\":\"xxxxxxxxx\",\"implementation_plan\":\"Software update is tested and results can be found in Test Summaries Tab.\",\"backout_plan\":\"When software fails in production, the previous software release will be re-deployed.\",\"test_plan\":\"Testing if the software was successfully deployed or not\"}}"

• changeStepDetails：[オプション] タイムアウトと間隔の詳細を保持します。
• interval：[オプション] API の試行間隔を秒単位で指定します。デフォルトの値は 100 秒です。
• timeout：[オプション] アクションが失敗するまで待機する最大時間 (秒)。デフォルトの値は 3600 秒です。
  注:

  ツールでここでタイムアウト値も使用できる場合は、それより前のタイムアウト値が考慮されます。
• attributes：[オプション] 変更要求属性の詳細は、ServiceNow インスタンスで変更を作成するときに使用されます。変更要求は、カンマ (,) で区切られたキーと値のペアを含む中括弧 {} で囲まれた JSON オブジェクトです。キーと値のペアは、コロン (:)で区切られたキーと値で構成されます。キーと値のペアでサポートされるキーは、short_description、description、assignment_group、implementation_plan、backout_plan、test_plan などです。
• -ctx：[オプション] JSON 形式の追加コンテキストパラメーター。DevOps 変更 API の要求をビルドするために使用される GitHub からの環境変数の詳細。例を次に示します。

  sndevopscli create change -ctx "{\"projectId\": \"123456\", \"attemptNumber\": \"${{ github.run_attempt }}\"}" -p "{\"changeStepDetails\": {\"timeout\":3600,\"interval\":100},\"autoCloseChange\":true,\"attributes\":{\"short_description\":\"G Venkata Automated Software Deployment\",\"description\":\"Automated Software Deployment.\",\"assignment_group\":\"a715cd759f2002002920bde8132e7018\",\"implementation_plan\":\"Software update is tested and results can be found in Test Summaries Tab.\",\"backout_plan\":\"When software fails in production, the previous software release will be re-deployed.\",\"test_plan\":\"Testing if the software was successfully deployed or not\"}}"

• -w：[オプション] パイプラインが変更の作成と承認を待機するかどうかを指定します。既定では、パイプラインは変更の作成とその承認まで待機します。

ServiceNow DevOps SonarScan 結果カスタムステップをジョブレベルで追加して、ServiceNowインスタンスに Sonar サマリーを作成します。例：

stages:
  - DevOpsSonarStage

ServiceNow DevOps SonarScan Results:
  stage: DevOpsSonarStage
  image: servicenowdocker/sndevops:6.2.0
  script: 
    - sndevopscli create sonar -url 'https://sonarcloud.io' -projectKey 'devsystem2019_TestImportTest'

• url：[必須] Sonar URL を指定します。
• projectKey：[必須] Sonar プロジェクトキーを指定します。

制限事項

ソフトウェア品質サマリー結果の作成中に、MERGE_REQUEST_SOURCE_BRANCH_NAME 環境変数はマージパイプラインに使用され、COMMIT_BRANCH変数はマージパイプラインまたはタグパイプラインで使用できないため、タグパイプラインにはDEFAULT_BRANCHが使用されます。詳細については、GitLab ドキュメントを参照してください。

アーティファクトをジョブレベルで追加して、 ServiceNow インスタンスにアーティファクトを登録します。例：

stages:
  - artifact

artifact:
  stage: artifact
  image: servicenowdocker/sndevops:6.2.0
  script: 
    - sndevopscli create artifact -a "[{\"name\":\"Artifact-${JOB_NAME}\",\"repositoryName\":\"Repo\",\"version\":\"1.${JOB_ID}.0\"}]"
 

パッケージのカスタムステップをジョブレベルで追加して、 ServiceNow インスタンスにパッケージを登録します。例：

stages:
  - package

package:
  stage: package
  image: servicenowdocker/sndevops:6.2.0
  script: 
    - sndevopscli create package -n "Package2" -a "[{\"name\":\"Artifact-${JOB_NAME}\",\"repositoryName\":\"Repo\" ,\"version\":\"1.${JOB_ID}.0\"}]"

例：

stages:
  - DevOpsGetChange

ServiceNow DevOps Get Change:
  stage: DevOpsGetChange
  image: servicenowdocker/sndevops:6.2.0
  script: 
    - sndevopscli get change -p "{\"buildNumber\":${CHG_JOB_ID},\"stageName\":\"ServiceNow DevOps Change Step\",\"pipelineName\":\"GitlabDockerGetAndUpdateChange\"}"

-p: It stands for changeDetails. The change details to be used for identifying change request in ServiceNow instance. The change details is a JSON object surrounded by curly braces {} containing key-value pair separated by a comma ,. A key-value pair consists of a key and a value separated by a colon :. The keys supported in key-value pair are buildNumber, pipelineName, stageName

buildNumber: [mandatory]
This specifies ID of the Job where we have created change request.

stageName: [mandatory]
This specifies the Job name where we have created change request..

pipelineName: [mandatory]
This specifies the pipeline name.

Outputs:
  sndevopschg.json file created with content: {
    "status": "SUCCESS",
    "changeRequestNumber": "CHGXXXXX"
  }
  
  changeRequestNumber: Change Request Number found for the given change details
  status: To know the status of the Change Request GET.

例：

stages:
  - DevOpsUpdateChangeStage

ServiceNow DevOps Update Change:
  stage: DevOpsUpdateChangeStage
  image: servicenowdocker/sndevops:6.2.0
  script: 
    - sndevopscli update change -n 'CHGXXXXXX' -p "{\"short_description\":\"G Venkata12345 Automated Software Deployment\",\"description\":\"Automated Software Deployment.\",\"assignment_group\":\"XXXXX\",\"implementation_plan\":\"Software update is tested and results can be found in Test Summaries Tab.\",\"backout_plan\":\"When software fails in production, the previous software release will be re-deployed.\",\"test_plan\":\"Testing if the software was successfully deployed or not\"}"

-n [Not mandatory if we have sndevopschg.json in our pipeline yml]: It stands for changeRequestNumber. The change request number to identify a unique change request. 
   Precedence of choosing changeRequestNumber: 
     - changeRequestNumber mentioned in the pipeline yml
     - changeRequestNumber stored in sndevopschg.json.

-p : It stands for changeDetails. The change details to be used for Updating the change request information identified by the specified change request number with the key-value pairs. The change details is a JSON object surrounded by curly braces {} containing key-value pair separated by a comma ,. A key-value pair consists of a key and a value separated by a colon :. The keys supported in key-value pair are short_description, state, description, work_notes ..so on

OR
  - sndevopscli update change -p "{\"short_description\":\"Updated Automated Software Deployment\",\"description\":\"Automated Software Deployment.\",\"assignment_group\":\"XXXXXXXXXX\",\"implementation_plan\":\"Software update is tested and results can be found in Test Summaries Tab.\",\"backout_plan\":\"When software fails in production, the previous software release will be re-deployed.\",\"test_plan\":\"Testing if the software was successfully deployed or not\"}"

NOTE: State should be specified at last in case if you are update the state of change request.
- sndevopscli update change -p "{\"short_description\":\"Updated Automated Software Deployment\",\"description\":\"Automated Software Deployment.\",\"assignment_group\":\"XXXXXXXXXX\",\"implementation_plan\":\"Software update is tested and results can be found in Test Summaries Tab.\",\"backout_plan\":\"When software fails in production, the previous software release will be re-deployed.\",\"test_plan\":\"Testing if the software was successfully deployed or not\","state":"3"}'

例：

stages:
  - changeapproval

ServiceNow DevOps Change Step:
  stage: changeapproval
  image: servicenowdocker/sndevops:6.2.0
  script: 
     - sndevopscli create change -p "{\"changeStepDetails\":{\"timeout\":3600,\"interval\":100},\"autoCloseChange\":true,\"attributes\":{\"short_description\":\"G Venkata Automated Software Deployment\",\"description\":\"Automated Software Deployment.\",\"assignment_group\":\"xxxxxxxx\",\"implementation_plan\":\"Software update is tested and results can be found in Test Summaries Tab.\",\"backout_plan\":\"When software fails in production, the previous software release will be re-deployed.\",\"test_plan\":\"Testing if the software was successfully deployed or not\"}}"
  
autoCloseChange: [optional] : Boolean value

ServiceNow DevOps Security Scan Results カスタムステップをジョブレベルで追加して、セキュリティスキャン結果を取得します。例：

stages:
  - DevOpsSecurityScanStageServiceNow 

ServiceNow DevOps Security Scan Results:
  stage: DevOpsSecurityScanStageimage 
  image: servicenowdocker/sndevops:6.2.0
  script: 
      - sndevopscli create securityScan -p "{\"pipelineInfo\":{\"buildNumber\":\"${PIPELINE_ID}\",\"pipelineExecutionUrl\":\"${PIPELINE_URL}\" },\"securityResultAttributes\":{ \"scanner\":\"Veracode\",\"applicationName\":\"PetStoreAPI-Github\",\"buildVersion\":\"\",\"securityToolId\":\"\"}}"
  -p: [mandatory]It the payload of security result attributes. The payload will have attributes as follows:
    buildNumber: PIPELINE_ID (mandatory)pipelineExecutionUrl: PIPELINE_URL (mandatory)scanner: Scanning tool and is required e.g. Checkmarx One.projectName/projectId: Name/Id of your Checkmarx One project and is required. This attribute is applicable only for Checkmarx One.applicationName: Name of your Veracode application and is required. This attribute is applicable only for Veracode.buildVersion": Veracode Scan name / build version and is optional. This attribute is applicable only for Veracode.scanId: Checkmarx One scan id and is optional. This attribute is applicable only for Checkmarx One.securityToolId: Security tool onboarded in ServiceNow (sys_id of the onboarded security tool) and is optional.