CodeBuild のビルド仕様に関するリファレンス

オプションのシーケンス。Linux または Windows オペレーティングシステムでサポートされるシェルを指定します。

Linux オペレーティングシステムで、サポートされているシェルタグは次のとおりです。

Windows オペレーティングシステムで、サポートされているシェルタグは次のとおりです。

env を指定し、プレーンテキストでカスタム環境変数を定義する場合は必須です。キーと値のスカラーのマッピングを含み、各マッピングはプレーンテキストで 1 つのカスタム環境変数を表します。キーは、カスタム環境変数の名前で、値はその変数の値です。

env が指定されていて、Amazon EC2 Systems Manager パラメータストアに保存されているカスタム環境変数を取得する場合は必須です。キーと値のマッピングを含み、各マッピングは単一のカスタム環境変数を表し、Amazon EC2 Systems Manager パラメータストアに保存されます。キーは、後でビルドコマンドで使用するこのカスタム環境変数を参照する名前で、値は Amazon EC2 Systems Manager パラメータストアに保存されているカスタム環境変数の名前です。重要な値を保存するには、Amazon EC2 Systems Manager ユーザーガイドの「Systems Manager パラメータストア」および「チュートリアル: String パラメータの作成とテスト (コンソール)」を参照してください。

に保存されているカスタム環境変数を取得する場合に必要です AWS Secrets Manager。次のパターンを使用して、Secrets Manager reference-key を指定します。

<key>: <secret-id>:<json-key>:<version-stage>:<version-id>

次の例で、TestSecret は Secrets Manager に保存されているキーと値のペアの名前です。TestSecret のキーは MY_SECRET_VAR です。ビルド中に変数にアクセスするには、名前「LOCAL_SECRET_VAR」を使用します。

env:
  secrets-manager:
    LOCAL_SECRET_VAR: "TestSecret:MY_SECRET_VAR"

詳細については、AWS Secrets Managerユーザーガイドの「AWS Secrets Manager とは?」を参照してください。

オプションのマッピング。エクスポートする環境変数をリストするために使用します。エクスポートする各変数の名前を、exported-variables の別の行で指定します。エクスポートする変数は、ビルド中にコンテナで使用できる必要があります。エクスポートする変数は、環境変数にすることができます。

エクスポートされた環境変数は、 と組み合わせて使用 AWS CodePipeline して、現在のビルドステージからパイプラインの後続のステージに環境変数をエクスポートします。詳細については、AWS CodePipeline ユーザーガイドの変数の操作を参照してください。

ビルド中、変数の値は、install フェーズから開始して使用できます。これは、install フェーズの開始と post_build フェーズの終了の間に更新することができます。post_build フェーズが終了すると、エクスポートされた変数の値は変更できません。

オプションのマッピング。CodeBuild が Git 認証情報ヘルパーを使用して Git 認証情報を提供するかどうかを示します。使用する場合は yes です。それ以外の場合は、no または指定なしです。詳細については、Git ウェブサイトの「gitcredentials」を参照してください。

オプションのマッピング。明示的なプロキシサーバーのビルドでアーティファクトをアップロードする場合は、yes に設定します。デフォルトは no です。

オプションのマッピング。明示的なプロキシサーバーのビルドで、CloudWatch ログを作成するには、yes に設定します。デフォルトは no です。

オプションのシーケンス。ビルドフェーズで使用し、そのコマンドを実行する Linux ユーザーを指定します。buildspec ファイルの上ですべてのコマンドに対して run-as もグローバルに指定されている場合、フェーズレベルのユーザーが優先されます。例えば、run-as がグローバルに User-1 を指定し、run-as ステートメントが install フェーズでのみ User-2 を指定した場合、buildspec ファイル内のすべてのコマンドは User-1 として実行されますが、install フェーズのコマンドは除きます (これらのコマンドは User-2 として実行されます)。

オプションのシーケンス。フェーズ中に障害が発生した場合に実行するアクションを指定します。これには、次のいずれかの値を指定できます。

このプロパティを指定しない場合は、ビルドフェーズの移行 に示すように、失敗処理が遷移フェーズに続きます。

オプションのブロック。finally ブロックに指定したコマンドは、commands ブロックのコマンドの実行後に実行されます。finally ブロックに指定したコマンドは、commands ブロックのコマンドが失敗した場合でも実行されます。例えば、commands ブロック内に 3 つのコマンドがあり、最初のコマンドが失敗した場合、CodeBuild は残りの 2 つのコマンドをスキップして finally ブロック内のコマンドを実行します。commands ブロックと finally ブロックのすべてのコマンドが正常に実行されると、フェーズは成功します。フェーズのいずれかのコマンドが失敗すると、フェーズは失敗します。

オプションのシーケンス。インストール時に CodeBuild が実行するコマンドがある場合は、そのコマンドを表します。install フェーズは、ビルド環境でのパッケージのインストールにのみ使用することをお勧めします。たとえば、このフェーズを使用して、Mocha や RSpec などのコードテストフレームワークをインストールすることができます。

オプションのシーケンス。ビルドの前に CodeBuild が実行するコマンドがあれば、それを表します。たとえば、このフェーズを使用して Amazon ECR にサインインするか、npm の依存関係をインストールすることができます。

オプションのシーケンス。ビルド中に CodeBuild が実行するコマンドがあれば、それを表します。たとえば、このフェーズを使用して、Mocha、RSpec、または sbt を実行できます。

オプションのシーケンス。ビルドの後に CodeBuild が実行するコマンドがあれば、それを表します。たとえば、Maven を使用してビルドアーティファクトを JAR または WAR ファイルにパッケージ化するか、Docker イメージを Amazon ECR にプッシュすることができます。次に、Amazon SNS を介してビルド通知を送信できます。

オプションのシーケンス。レポートの送信先のレポートグループを指定します。プロジェクトには、最大 5 つのレポートグループを含めることができます。既存のレポートグループの ARN、または新しいレポートグループの名前を指定します。名前を指定した場合、CodeBuild は、プロジェクト名と <project-name>-<report-group-name> 形式で指定した名前を使用してレポートグループを作成します。レポートグループ名は、$REPORT_GROUP_NAME などの buildspec の環境変数を使用して設定することもできます。詳細については、「Report group naming」を参照してください。

必要なシーケンス。レポートによって生成されたテスト結果の生データを含む場所を表します。スカラーのシーケンスが含まれます。各スカラーは、元のビルドの場所または base-directory (設定されている場合) を基準にして、CodeBuild がテストファイルを検索できる個別の場所を表します。場所には次のものが含まれます。

オプションのマッピング。レポートファイル形式を表します。指定しない場合は、JUNITXML を使用します。この値は大文字と小文字が区別されません。想定される値は次のとおりです。

オプションのマッピング。CodeBuild が生のテストファイルを見つける場所を決定するために使用する元のビルド場所に対する相対的な 1 つ以上のトップレベルディレクトリを表します。

オプション。レポートファイルのディレクトリを出力でフラット化するかどうかを指定します。これが指定されていない場合、または no を含む場合、レポートファイルはディレクトリ構造のまま出力されます。このディレクトリに yes が含まれている場合、すべてのテストファイルが同じ出力ディレクトリに配置されます。たとえば、テスト結果へのパスが com/myapp/mytests/TestResult.xml である場合、yes を指定すると、このファイルが /TestResult.xml に配置されます。

必要なシーケンス。ビルド環境でのビルド出力アーティファクトを含む場所を表します。スカラーのシーケンスが含まれ、各スカラーは、CodeBuild が元のビルドの場所を基準に、あるいは設定されている場合はベースディレクトリを基準にして、ビルド出力アーティファクトを見つけることができる個別の場所を表します。場所には次のものが含まれます。

ビルド出力アーティファクトの場所を指定すると、CodeBuild はビルド環境で元のビルドの場所を特定できます。ビルドアーティファクトの出力先の場所に、元のビルドの場所へのパスを追加する、または ./ などで場所を指定する必要はありません。この場所へのパスを知りたい場合は、ビルド中に echo $CODEBUILD_SRC_DIR などのコマンドを実行できます。各ビルド環境の場所は多少異なる場合があります。

オプション名。ビルドアーティファクトの名前を指定します。この名前は、次のいずれかに該当する場合に使用されます。

ビルド時に計算される buildspec ファイルの名前を指定できます。buildspec ファイルで指定された名前は、Shell コマンド言語を使用します。たとえば、アーティファクト名に日付と時刻を追加して常に一意にできます。アーティファクト名を一意にすると、アーティファクトが上書きされるのを防ぐことができます。詳細については、「Shell コマンド言語」を参照してください。

名前にパス情報を追加して、名前のアーチファクトが名前のパスに基づいてディレクトリに配置されるようにできます。この例では、ビルドアーティファクトは、builds/<build number>/my-artifacts の下に配置されます。

version: 0.2
phases:
  build:
    commands:
      - rspec HelloWorld_spec.rb
artifacts:
  files:
    - '**/*'
  name: builds/$CODEBUILD_BUILD_NUMBER/my-artifacts

オプション。ビルドアーティファクトのディレクトリが出力でフラット化されるかどうかを指定します。これが指定されていない場合、または no を含む場合は、ディレクトリ構造はそのままで、ビルドアーティファクトが出力されます。このディレクトリに yes が含まれる場合、すべてのビルドアーティファクトが同じ出力ディレクトリに配置されます。たとえば、ビルド出力アーティファクト内のファイルへのパスが com/mycompany/app/HelloWorld.java である場合、yes を指定すると、このファイルが /HelloWorld.java に配置されます。

オプションのマッピング。CodeBuild がビルド出力アーティファクトに含めるファイルとサブディレクトリを決定するために使用する、元のビルドの場所を基準とした、1 つ以上の最上位ディレクトリを表します。有効な値を次に示します。

一致する最上位ディレクトリはビルド出力アーティファクトに含まれず、ファイルとサブディレクトリにのみ含まれます。

files および discard-paths を使用して、どのファイルとサブディレクトリを含めるかをさらに制限できます。たとえば、以下のようなディレクトリ構造があります。

.
├── my-build-1
│   └── my-file-1.txt
└── my-build-2
    ├── my-file-2.txt
    └── my-subdirectory
        └── my-file-3.txt

また、次のような artifacts シーケンスがあります。

artifacts:
  files:
    - '*/my-file-3.txt'
  base-directory: my-build-2

次のサブディレクトリとファイルが、ビルド出力アーティファクトに含まれます。

.
└── my-subdirectory
    └── my-file-3.txt

さらに、次のような artifacts シーケンスがあります。

artifacts:
  files:
    - '**/*'
  base-directory: 'my-build*'
  discard-paths: yes

次のファイルが、ビルド出力アーティファクトに含まれます。

.
├── my-file-1.txt
├── my-file-2.txt
└── my-file-3.txt

オプションのマッピング。base-directory に相対的な 1 つまたは複数のパスを表します。CodeBuild はビルドのアーティファクトから、このパスを除外します。アスタリスク (*) 記号は、フォルダの境界を超えない、0 文字以上の名前の要素と一致します。二重アスタリスク (**) は、すべてのディレクトリをまたいで、0 文字以上の名前の要素と一致します。

除外パスの例は以下のとおりです。

オプション。出力タイプが ZIP の場合、内部シンボリックリンクを ZIP ファイルに保持するかどうかを指定します。これに yes が含まれる場合、ソース内のすべての内部シンボリックリンクがアーティファクト ZIP ファイルに保持されます。

オプション。アーティファクトを Amazon S3 バケットに出力し、名前空間タイプが BUILD_ID の場合に使用するプレフィックスを指定します。使用した場合、バケット内の出力パスは「<s3-prefix>/<build-id>/<name>.zip」となります。

オプションのシーケンス。アーティファクト識別子とアーティファクト定義との間のマッピングとしての 1 つ以上のアーティファクト定義を表します。このブロック内の各アーティファクト識別子は、プロジェクトの secondaryArtifacts 属性で定義されたアーティファクトと一致する必要があります。各個別の定義は、上記の artifacts ブロックと同じ構文を持っています。

たとえば、プロジェクトに次の構造があるとします。

{
  "name": "sample-project",
  "secondaryArtifacts": [
    {
      "type": "S3",
      "location": "<output-bucket1>",
      "artifactIdentifier": "artifact1",
      "name": "secondary-artifact-name-1"
    },
    {
      "type": "S3",
      "location": "<output-bucket2>",
      "artifactIdentifier": "artifact2",
      "name": "secondary-artifact-name-2"
    }
  ]
}

次に、buildspec は次のようになります。

version: 0.2

phases:
build:
  commands:
    - echo Building...
artifacts:
  files:
    - '**/*'
  secondary-artifacts:
    artifact1:
      files:
        - directory/file1
      name: secondary-artifact-name-1
    artifact2:
      files:
        - directory/file2
      name: secondary-artifact-name-2

オプションのシーケンス。キャッシュを検索または復元するときに使用されるプライマリキーを表します。CodeBuild はプライマリキーと完全に一致します。

キーの例を次に示します。

key: npm-key-$(codebuild-hash-files package-lock.json) }

オプションのシーケンス。プライマリキーを使用してキャッシュが見つからない場合に順次使用されるフォールバックキーのリストを表します。最大 5 つのフォールバックキーがサポートされ、それぞれがプレフィックス検索を使用して照合されます。キーが指定されていない場合、このシーケンスは無視されます。

フォールバックキーの例を次に示します。

fallback-keys:
    - npm-key-$(codebuild-hash-files package-lock.json) }
    - npm-key-
    - npm-

オプションのシーケンス。キャッシュで実行するアクションを指定します。有効な値を次に示します。

値が指定されていない場合、CodeBuild はデフォルトで復元と保存の両方を実行します。

必要なシーケンス。キャッシュの場所を表します。スカラーのシーケンスが含まれ、各スカラーは、CodeBuild が元のビルドの場所を基準に、あるいは設定されている場合はベースディレクトリを基準にして、ビルド出力アーティファクトを見つけることができる個別の場所を表します。場所には次のものが含まれます。