Oracle Cloud Infrastructureドキュメント

ビルド仕様

ビルド仕様には、ビルド・パイプラインがビルドの実行に使用するビルド・ステップおよび設定が含まれています。

ビルド仕様は、YAMLで記述されます。デフォルトでは、ビルド仕様はプライマリ・ビルド・ソース・ディレクトリのルートにあり、ビルド・パイプラインの実行時に使用されます。このファイルは、build_spec.ymlまたはbuild_spec.yamlという名前です。ビルド仕様がルート・ディレクトリに存在しない場合は、「マネージド・ビルド」ステージを追加するときにファイルの相対パスを指定する必要があります。

ビルド仕様は、次のセクションで構成されています:

  • ビルド・ランナーの構成。
  • 環境変数の設定。
  • 入力アーティファクト。
  • 順番に実行するステップ。
  • 出力アーティファクト。

ビルド仕様の構文

version: 0.1
component: build
timeoutInSeconds: 10000
shell: bash
failImmediatelyOnError: true
env:
  variables:
    key: "value"
    key: "value"
  vaultVariables:
    key: "secret-id"
  exportedVariables:
    - variable
    - variable
    - variable

inputArtifacts:
  - name: artifact-name
    type: GENERIC_ARTIFACT
    artifactId: "artifact-ocid"
    registryId: OCID of the Artifact Registry
    path: path of the artifact in the Registry
    version: version of the artifact
    location: target-location
  - name: artifact-name
    type: STAGE_ARTIFACT
    location: target-location
  - name: artifact-name
    type: URL
    url: downloadable link
    location: target-location

steps:
  - type: Command
    name: step-name
    shell: shellType
    timeoutInSeconds: 650
    failImmediatelyOnError: true
    command: command
    onFailure:
      - type: Command
        command: |
          command
          command
        timeoutInSeconds: 400

  - type: Command
    name: step-name
    command: |
      command
      command
      command
    onFailure:
      - type: Command
        command: |
          command
        timeoutInSeconds: 400

outputArtifacts:
  - name: artifact-name
    type: artifact-type
    location: source-location
ノート

sudoは、ビルド・ランナー・ホストでは使用できません。スーパーユーザー権限が必要な場合は、rootユーザーとしてビルド・ステップを実行します。

ビルド仕様のパラメータ

次に、ビルド仕様のパラメータとその詳細を示します:

パラメータ 説明
version 必須。ビルド仕様のバージョンを示します。バージョンが存在しないか無効であると、ビルド・ステージは失敗します。

サポートされる値は0.1です。
component 必須。DevOpsの特定のコンポーネントを示します。値が存在しないか無効であると、ビルドは失敗します。

サポートされる値はbuildです。
timeoutInSeconds オプション。ビルド仕様ファイル全体のタイムアウトを指定します。各ステップには、オプションで独自のタイムアウト値を指定することもできます。

値を指定しない場合、デフォルト値の8時間が使用されます。許可される最大値は8時間です。
shell オプション。ビルド仕様のグローバル・レベルで使用するシェルを指定します。値は、オプションでステップ・レベルでオーバーライドできます。

許可される値は/bin/shおよびbashです。指定しない場合、デフォルト値のbashが使用されます。
failImmediatelyOnError オプション。ステップ内のいずれかのコマンドがゼロ以外の終了値で失敗した場合にビルドを続行する必要があるかどうかを指定します。指定しない場合、デフォルト値はfalseで、ステップは続行されます。使用可能な値はtrueおよびfalseです。OCIでは、この属性の値をtrueに設定することをお薦めします。
env

オプション。カスタム変数を定義できます。3つのタイプの変数がサポートされます:

  • env/variables: オプション。キーは文字列で、POSIX環境変数に準拠している必要があります。値には任意の文字列を指定できます。この変数のスコープは、ビルド仕様ファイルの実行です。変数の値の変更は、後続のステップで認識されます。これらの変数は、ビルド仕様ファイル内のすべてのステップの環境変数として使用できます。

    変数の値に改行(\n)またはキャリッジ・リターン(\r)文字が含まれている場合は、後続のステップでスペースに置き換えられます。

  • env/vaultVariables: オプション。キーは文字列で、POSIX環境変数に準拠している必要があります。この値は、ボールトからのシークレットのOCIDである必要があります。ボールトとビルド・パイプラインは、同じテナンシである必要があります。テナンシには、ビルド・パイプライン・リソースがシークレットにアクセスすることを許可する適切なポリシーが必要です。

    この変数のスコープは、ビルド仕様ファイルの実行であり、ファイル内のすべてのステップで使用できます。これらの変数の値は、ボールトから取得され、ビルド仕様ファイル内のすべてのステップの環境変数として使用できます。

  • env/exportedVariables: オプション。変数のリストはここで宣言できます。変数名は文字列で、POSIX環境変数に準拠している必要があります。この値は、ビルド仕様ファイル内のいずれかのステップで割り当てることができます。この変数のスコープは、ビルド・パイプラインです。エクスポートされた変数は、同じパイプラインの後続のステージで使用できます。
inputArtifacts

オプション。現在のビルド・ステージの実行に必要な入力アーティファクトのリストを定義するために使用されます。

次のタイプの入力アーティファクトがサポートされます:
  • 前のいずれかのビルド・ステージからのアーティファクト。
  • 外部のダウンロード可能HTTP URLからのアーティファクト。
  • アーティファクト・レジストリからの汎用アーティファクト。

パラメータは次のとおりです:

  • inputArtifacts/*/url: オプション。入力アーティファクトの外部のダウンロード可能HTTP URLを指定する必要があります。URLはパブリックに使用可能である必要があります。現在、認証/認可はサポートされていません。
  • inputArtifacts/*/name: 必須。URLが存在しない場合、この名前は、同じパイプラインの前のビルド・ステージで生成されたアーティファクトを検索するために使用されます。そのため、パイプラインの前のビルド・ステージで生成された特定のアーティファクトを消費するためには、outputArtifacts/nameとinputArtifacts/nameが一致している必要があります。
  • inputArtifacts/*/location: 必須。入力アーティファクトをダウンロードする必要があるローカル・ファイル・システムの宛先パス。パスは次のいずれかの方法で指定できます:
    • ${OCI_PRIMARY_SOURCE_DIR}/pom.xml
    • ${OCI_WORKSPACE_DIR}/[source-name]/pom.xml
    • /workspace/[source-name]/pom.xml
    • プロジェクト・ホームからの相対パス、pom.xml

    いずれかの値を使用すると、入力アーティファクトがファイル名pom.xmlでプライマリ・ソース・ホーム・ディレクトリにダウンロードされます。

    locationでは、exportedVariablesまたはパイプライン変数はサポートされていません。

  • inputArtifacts/*/type: 必須。ダウンロードする必要がある入力アーティファクトのタイプ。許可される値はURL、STAGE_ARTIFACTおよび GENERIC_ARTIFACTです。
  • inputArtifacts/*/artifactld: 必須。アーティファクトのOCID。OCIDを指定した場合、ビルド・パイプラインはregistryId、パスおよびバージョンを無視します。
  • inputArtifacts/*/registryld: 必須。アーティファクト・レジストリのOCID。
  • inputArtifacts/*/path: 必須。アーティファクトの宛先パス。
  • inputArtifacts/*/version: 必須。アーティファクトのバージョン。
ノート

GENERIC_ARTIFACTタイプの入力アーティファクトの場合、必須パラメータとしてアーティファクトのOCID、またはレジストリID、パスおよびアーティファクト・バージョンの組合せを指定できます。
steps

必須。このセクションでは、実行する必要があるステップのリストを定義します。

  • steps/*/type: 必須。ステップのタイプを指定します。Command、VulnerabilityAuditの値がサポートされます。詳細は、ステップのタイプを参照してください。
  • steps/*/name: オプション。ステップのわかりやすい名前。
outputArtifacts

オプション。ビルド・ステージで生成されたアーティファクトを指定します。このセクションの出力として生成されたアーティファクトは、現在のビルド実行の存続期間中保存されます。これらは、ビルド・パイプラインの後続のステージで使用できます。

  • outputArtifacts/*/name: 必須。名前には、小文字(a-z)、大文字(A-Z)、アンダースコア(_)およびハイフン(-)を使用できます。名前は、出力アーティファクトの一意の識別子です。ビルド・パイプラインの後続のステージでは、アーティファクトを識別するために名前が使用されます。
  • outputArtifacts/*/type: 必須。許可される値はBINARYおよびDOCKER_IMAGEです。

    BINARY: 出力アーティファクトとしてバイナリ・ファイルを指定します。

    outputArtifacts/*/location: 出力アーティファクトが見つかるローカル・ファイル・システムのソース・パス。パスは、次のいずれかの方法で指定できます(プライマリ・ソース・ホーム・ディレクトリにpom.xmlファイルが存在するとします):

    • ${OCI_PRIMARY_SOURCE_DIR}/pom.xml
    • ${OCI_WORKSPACE_DIR}/[source-name]/pom.xml
    • /workspace/[source-name]/pom.xml
    • プロジェクト・ホームからの相対パス、pom.xml

    指定された場所にファイルが見つからない場合、ビルド・ステージは失敗します。

    DOCKER_IMAGE: 出力アーティファクトとしてDockerイメージを指定します。

    outputArtifacts/*/location: ビルド仕様ファイルのいずれかのステップに基づいてビルドされたDockerイメージ・タグ。

    たとえば、ビルド仕様ファイルのいずれかのステップで、Dockerイメージがdocker build -t iad.ocir.io/id204we8d65n/hello-world:1.0としてビルドされた場合、このアーティファクトを生成するには、locationフィールドにiad.ocir.io/id204we8d65n/hello-world:1.0が含まれている必要があります。

    イメージをビルドまたはプルして、ビルド仕様ステップのいずれかで使用できるようにする必要があります。そうしないと、outputArtifactステップは失敗し、最終的にビルド・ステージも失敗します。

    locationでは、exportedVariablesまたはパイプライン変数はサポートされていません。

ステップのタイプ

コマンド

属性名 説明
command 単一行と複数行の両方のコマンドがサポートされます。1つのステップで指定されているすべてのコマンドは、同じシェル・セッションで実行されます。steps/*/shellの値に基づいて、コマンドはshellまたはbashのいずれかになります。

フェイル・ファストは有効になっていません。ステップの成功については、ステップの最終コマンドの出力が考慮されます。最終コマンドの終了コードが0の場合、ステップは成功とみなされます。
timeoutInSeconds (オプション) ステップのタイムアウトを指定します。指定しない場合、値はグローバルtimeoutInSecondsパラメータから継承されます。許可される最大値は8時間です。
shell (オプション) 現在のステップのシェル・タイプを指定します。指定しない場合、値はグローバルshellパラメータから継承されます。許可される値は/bin/shおよびshellです。
onFailure (オプション) ビルド・ステージを正常に終了するために失敗時に実行する必要があるステップのリスト。対応するステップが失敗し、実行後にビルド仕様が終了した場合に実行します。

失敗の処理は、ビルド・ステージのステータスに影響しません。いずれかのステップが失敗した場合、ビルド・ステージのステータスはfailedのままになりますが、onFailureブロックを使用して処理されます。
failImmediatelyOnError (オプション) ステップ内のいずれかのコマンドがゼロ以外の終了値で失敗した場合にビルドを続行する必要があるかどうかを指定します。指定しない場合、デフォルト値はfalseで、ステップは続行されます。使用可能な値はtrueおよびfalseです。OCIでは、この属性の値をtrueに設定することをお薦めします。

stepsで定義されているfailImmediatelyOnError属性値は、stepsの外部で定義されている同じ属性値よりも優先されます。

脆弱性監査

脆弱性監査は、アプリケーションとその依存関係の脆弱性を示します。OCI DevOpsサービスを使用してビルドを実行するときに、コード・リポジトリへの新しいコミットに対してコード・スキャンを開始できます。脆弱性監査は、「マネージド・ビルド」ステージで行われます。

ビルド仕様ファイルでは、タイプVulnerabilityAuditの脆弱性監査ステップが追加され、DevOpsビルド・パイプラインでコード・スキャンのビルド実行中に使用されます。このステップの属性は次のとおりです:

属性名 説明 パラメータ化された値のサポート
name (オプション) ステップの名前。 該当なし
vulnerabilityAuditName (オプション) 脆弱性監査リソースの名前。 はい
vulnerabilityAuditCompartmentId (オプション)

デフォルトはknowledgeBaseCompartmentIdです

 監査リソースを作成する必要があるコンパートメントのOCID。 はい
knowledgeBaseId (必須) 脆弱性監査リソースの詳細を保持するためのプレースホルダ/タグのOCID。脆弱性監査リソースの親リソース。 はい
configuration/buildType (必須) ビルド・ツール・タイプ。 該当なし
configuration/pomFilePath (必須) pom.xmlファイルの場所。 はい
configuration/packagesToIgnore (オプション) 脆弱性監査の実行中にスキャン結果を計算するときに無視するJavaパッケージのリスト。 該当なし
configuration/maxPermissibleCvssV2Score (オプション)

デフォルトは0.0です

 脆弱性監査で許可される最大v2 CVSSスコア。この構成を超えた場合、ビルドをFailedとしてマークする必要があります。 該当なし
configuration/maxPermissibleCvssV3Score (オプション)

デフォルトは0.0です

 脆弱性監査で許可される最大v3 CVSSスコア。この構成を超えた場合、ビルドをFailedとしてマークする必要があります。 該当なし
freeFormTags (オプション) キーと値のペアを受け入れます。 該当なし

事前定義済システム変数

DevOpsには、ビルド仕様の環境変数など、使用可能なデフォルト値を持つ事前定義済システム変数のセットがあります。

変数 説明
OCI_STAGE_ID 現在のステージのOCID。
OCI_PIPELINE_ID 現在のビルド・パイプラインのOCID。
OCI_BUILD_RUN_ID 現在のビルド実行のOCID。
OCI_TRIGGER_COMMIT_HASH 現在のトリガーのコミット・ハッシュ。
OCI_TRIGGER_SOURCE_BRANCH_NAME ビルドをトリガーするブランチ。
OCI_TRIGGER_SOURCE_URL ビルドをトリガーしたリポジトリURL
OCI_TRIGGER_EVENT_TYPE イベントを開始したトリガー。
OCI_PRIMARY_SOURCE_DIR ビルドのデフォルトの作業ディレクトリ(プライマリ・ソースの作業ディレクトリ)。
OCI_WORKSPACE_DIR 作業ディレクトリの値。デフォルト値として/workspaceを含みます。
${OCI_WORKSPACE_DIR}/<source-name> ビルド・ソース・ディレクトリ・パス。

source-nameは、ビルド・ステージの作成中にユーザーが指定したビルド・ソースの名前です。
OCI_BUILD_STAGE_NAME ビルド・ステージ名。
OCI_PRIMARY_SOURCE_NAME プライマリ・ビルド・ソース名。
OCI_PRIMARY_SOURCE_COMMIT_HASH 現在のビルド実行で使用されるプライマリ・ビルド・ソースのコミット・ハッシュ。
OCI_PRIMARY_SOURCE_URL プライマリ・ビルド・ソースのURL。
OCI_PRIMARY_SOURCE_BRANCH_NAME 現在のビルド実行で使用されるプライマリ・ビルド・ソースのブランチ。

ビルド仕様の例

例1:

version: 0.1             
component: build
timeoutInSeconds: 1000
shell: bash           

steps:
  - type: Command
    name: "Build app"
    command: |
      mvn clean install

例2:

version: 0.1
component: build
timeoutInSeconds: 6000
shell: bash
failImmediatelyOnError: true
env:
  exportedVariables:
    - BuildServiceDemoVersion

steps:
  - type: Command
    name: "Build Source"
    timeoutInSeconds: 4000
    failImmediatelyOnError: true
    command: |
      echo $PATH
      mvn clean install
  - type: Command
    timeoutInSeconds: 400
    name: "Dockerizer"
    command: |
      BuildServiceDemoVersion=`echo ${OCI_BUILD_RUN_ID} | rev | cut -c 1-7`
      echo $BuildServiceDemoVersion
      docker build -t build-service-demo

  - type: VulnerabilityAudit
    name: "Scan my maven repo"
    vulnerabilityAuditName: Report-${buildRunId}
    vulnerabilityAuditCompartmentId: ocid1.compartment.oc1.iad.restoftheocid
    knowledgeBaseId: ocid1.knowledgebase.oc1.iad.restoftheocid
    configuration:
      buildType: maven
      pomFilePath: ./pom.xml
      packagesToIgnore:
        - "oracle.jdbc.*"
        - "org.apache.logging.log4j:1.2"
      maxPermissibleCvssV2Score: 5.0  
      maxPermissibleCvssV3Score: 5.1
      freeFormTags:
                  key1: value1
                  key2: value2

outputArtifacts:
  - name: build-service-demo
    type: DOCKER_IMAGE
    location: build-service-demo
  - name: build-service-demo-kube-manifest
    type: BINARY
    location: deployment/app.yml

例3:

version: 0.1
component: build
timeoutInSeconds: 6000
shell: bash

# Variables
env:
  variables:
    "testEnv" : "testValue1"
  vaultVariables:
    docker_registry_password : <secret-ocid>
  exportedVariables:
    - patch_number
    - build_Result

inputArtifacts:
  - name: hello-dev-jar 
    type: STAGE_ARTIFACT
    location: /workspace/Source/hello123.class
  - name: public-artifact
    type: URL
    url: https://raw.githubusercontent.com/apache/kafka/trunk/README.md  #URL must be publicly accessible
    location: /workspace/Source/readme.md
  - name: shell_script
    type: GENERIC_ARTIFACT
    artifactId: ocid1.genericartifact.oc1.iad.0.restoftheocid #appropriate policy is required for access
    location: /workspace/Source/script.sh
  - name: shell_script
    type: GENERIC_ARTIFACT
    registryId: ocid1.artifactrepository.oc1.iad.0.restoftheocid #appropriate policy is required for access
    path: some_script.sh
    version: 2.0
    location: /workspace/Source/script.sh

steps:
  - type: Command
    name: "Build Source"
    timeoutInSeconds: 4000
    shell: /bin/sh
    command: |
      # oci cli pre configured with build pipeline resource principal
      oci os ns get
      javac HelloWorld.java
    onFailure:
      - type: Command
        timeoutInSeconds: 400
        shell: /bin/sh
        command: |
          echo "Handling Failure"
          build_result=FAILURE
          echo "Failure successfully handled"
        timeoutInSeconds: 400
  - type: Command
    timeoutInSeconds: 400
    name: "Dockerizer & Test"
    command: |
      docker build -t test-image .
    onFailure:
      - type: Command
        command: |
          echo "Handling Failure"
          build_result=FAILURE
          echo "Failure successfully handled"
        timeoutInSeconds: 400
  - type: Command
    timeoutInSeconds: 400
    name: "Dockerizer & Test"
    command: |
      build_result=SUCESS
      patch_number==`echo ${OCI_BUILD_RUN_ID} | rev | cut -c 1-7`
        
outputArtifacts:
  - name: kube-manifest
    type: BINARY
    location: ${OCI_WORKSPACE_DIR}/Source/app.yml
  - name: hello-dev-image
    type: DOCKER_IMAGE
    location: test-image
ノート

高パフォーマンスのJavaアプリケーションをビルド・パイプラインにOracle GraalVMを使用できます。DevOpsビルド・パイプラインでOracle GraalVMをインストールして使用するには、ビルド仕様ファイルを更新する必要があります。詳細および例は、DevOpsビルド・パイプラインのOracle GraalVMの使用を参照してください。