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

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

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

このトピックでは、ビルド仕様 (buildspec) ファイルに関する重要なリファレンス情報を提供します。ABuildSpecCodeBuildがビルドを実行するために使用する YAML 形式のビルドコマンドと関連設定のコレクションです。buildspec をソースコードの一部として含めることも、ビルドプロジェクトの作成時に buildspec を定義することもできます。ビルド仕様の仕組みについては、「CodeBuild の仕組み」を参照してください。

buildspec ファイル名とストレージの場所

buildspec をソースコードの一部として含める場合、デフォルトの buildspec ファイルの名前は buildspec.yml で、ソースディレクトリのルートに配置する必要があります。

デフォルトの buildspec ファイルの名前と場所を変更することができます。たとえば、以下のことが可能です。

  • 同じリポジトリ内の異なるビルドに、buildspec_debug.ymlbuildspec_release.yml などの異なる buildspec ファイルを使用する。

  • config/buildspec.yml など、ソースディレクトリのルート以外の場所や、S3 バケットに buildspec ファイルを保存する。S3 バケットは、ビルドプロジェクトと同じ AWS リージョンに存在する必要があります。ARN を使用して buildspec ファイルを指定します(例: arn:aws:s3:::my-codebuild-sample2/buildspec.yml)。

buildspec ファイルの名前に関係なく、ビルドプロジェクトには 1 つの buildspec しか指定できません。

デフォルトの buildspec ファイルの名前、場所、またはその両方をオーバーライドするには、次のいずれかを実行します。

  • AWS CLI を実行するcreate-projectまたはupdate-projectコマンドで、buildspecの値を、組み込みの環境変数の値を基準にした代替 buildspec ファイルのパスに設定します。CODEBUILD_SRC_DIR。また、で同等の処理を行うこともできますcreate projectオペレーションを AWS SDK で設定します。詳細については、「ビルドプロジェクトの作成」または「ビルドプロジェクトの設定の変更」を参照してください。

  • AWS CLI を実行するstart-buildコマンドで、buildspecOverrideの値を、組み込みの環境変数の値を基準にした代替 buildspec ファイルのパスに設定します。CODEBUILD_SRC_DIR。また、で同等の処理を行うこともできますstart buildオペレーションを AWS SDK で設定します。詳細については、「ビルドの実行」を参照してください。

  • AWS CloudFormation テンプレートで、BuildSpecの プロパティSourceタイプのリソースでAWS::CodeBuild::Projectのパスを、組み込みの環境変数の値を基準にした代替 buildspec ファイルのパスに設定します。CODEBUILD_SRC_DIR。詳細については、「」の「BuildSpec」プロパティを参照してください。AWS CodeBuild プロジェクトソース()AWS CloudFormation ユーザーガイド

buildspec の構文

buildspec ファイルは YAML 形式で表現する必要があります。

YAML でサポートされていない文字または文字列がコマンドに含まれている場合は、そのコマンドを引用符 ("") で囲む必要があります。次のコマンドが引用符で囲まれているのは、YAML ではコロン (:) に続けてスペースを使用できないためです。コマンド内の引用符はエスケープ (\") されます。

"export PACKAGE_NAME=$(cat package.json | grep name | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g')"

buildspec の構文は次のとおりです。

version: 0.2 run-as: Linux-user-name env: shell: shell-tag variables: key: "value" key: "value" parameter-store: key: "value" key: "value" exported-variables: - variable - variable secrets-manager: key: secret-id:json-key:version-stage:version-id git-credential-helper: no | yes proxy: upload-artifacts: no | yes logs: no | yes batch: fast-fail: false | true # build-list: # build-matrix: # build-graph: phases: install: run-as: Linux-user-name on-failure: ABORT | CONTINUE runtime-versions: runtime: version runtime: version commands: - command - command finally: - command - command pre_build: run-as: Linux-user-name on-failure: ABORT | CONTINUE commands: - command - command finally: - command - command build: run-as: Linux-user-name on-failure: ABORT | CONTINUE commands: - command - command finally: - command - command post_build: run-as: Linux-user-name on-failure: ABORT | CONTINUE commands: - command - command finally: - command - command reports: report-group-name-or-arn: files: - location - location base-directory: location discard-paths: no | yes file-format: report-format artifacts: files: - location - location name: artifact-name discard-paths: no | yes base-directory: location exclude-paths: excluded paths enable-symlinks: no | yes s3-prefix: prefix secondary-artifacts: artifactIdentifier: files: - location - location name: secondary-artifact-name discard-paths: no | yes base-directory: location artifactIdentifier: files: - location - location discard-paths: no | yes base-directory: location cache: paths: - path - path

buildspec には、次のものが含まれています。

version

必要なマッピング。buildspec のバージョンを表します。0.2 を使用することをお勧めします。

注記

バージョン 0.1 も引き続きサポートされていますが、可能な場合はバージョン 0.2 を使用することをお勧めします。詳細については、「buildspec のバージョン」を参照してください。

run-as

オプションのシーケンス。Linux ユーザーのみが使用できます。この buildspec ファイルでコマンドを実行する Linux ユーザーを指定します。run-asは、指定されたユーザーに読み取りと実行のアクセス許可を付与します。buildspec ファイルの上で run-as を指定すると、すべてのコマンドにグローバルに適用されます。すべての buildspec ファイルコマンドのユーザーを指定しない場合、phases ブロックのいずれかで run-as を使用することによりフェーズでいずれかのコマンドを指定できます。run-as を指定しない場合、すべてのコマンドがルートユーザーとして実行されます。

env

オプションのシーケンス。1 つ以上のカスタム環境変数の情報を表します。

注記

機密情報を保護するために、CodeBuild ログでは次の情報が非表示になっています。

環境/シェル

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

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

  • bash

  • /bin/sh

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

  • powershell.exe

  • cmd.exe

env/variables

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

重要

機密情報、特に AWS アクセスキー ID とシークレットアクセスキーを環境変数に保存しないことを強くお勧めします。環境変数は、CodeBuild コンソールや AWS CLI などのツールを使用してプレーンテキストで表示できます。機密情報については、このセクションの後半で説明するように、parameter-store マッピングまたは secrets-manager マッピングを代わりに使用することをお勧めします。

既存の環境変数は、設定した環境変数によって置き換えられます。たとえば、Docker イメージに my_value の値を持つ MY_VAR という名前の環境変数が既に含まれていて、other_value の値を持つ MY_VAR という名前の環境変数を設定した場合、my_valueother_value に置き換えられます。同様に、Docker イメージに /usr/local/sbin:/usr/local/bin の値を持つ PATH という名前の環境変数が既に含まれていて、$PATH:/usr/share/ant/bin の値を持つ PATH という名前の環境変数を設定した場合、/usr/local/sbin:/usr/local/bin はリテラル値 $PATH:/usr/share/ant/bin に置き換えられます。

CODEBUILD_ で始まる名前の環境変数は設定しないでください。このプレフィックスは内部使用のために予約されています。

同じ名前の環境変数が複数の場所で定義されている場合は、その値は次のように決定されます。

env/parameter-store

では必須envが指定されていて、Amazon EC2 Systems Manager Parameter Store に保存されているカスタム環境変数を取得する場合は必須です。のマッピングを含む key/value スカラーが含まれ、各マッピングは Amazon EC2 Systems Manager Parameter Store に保存されている 1 つのカスタム環境変数を表します。key 後でビルドコマンドで使用するこのカスタム環境変数を参照する名前で、value は、Amazon EC2 Systems Manager Parameter Store に保存されているカスタム環境変数の名前です。機密性の高い値を格納するには、Systems Manager パラメータストアおよびウォークスルー: String パラメータの作成とテスト (コンソール)()Amazon EC2 Systems Manager ユーザーガイド

重要

CodeBuild が Amazon EC2 Systems Manager Parameter Store に保存されているカスタム環境変数を取得するには、ssm:GetParametersアクションを CodeBuild サービスロールに追加します。詳細については、「CodeBuild サービスロールの作成」を参照してください。

Amazon EC2 Systems Manager Parameter Store から取得する環境変数は、既存の環境変数を置き換えます。たとえば、Docker イメージに MY_VAR という名前で値が my_value の環境変数がすでに含まれていて、MY_VAR という名前で値が other_value の環境変数を取得した場合、my_valueother_value に置き換えられます。同様に、Docker イメージに PATH という名前で値が /usr/local/sbin:/usr/local/bin の環境変数がすでに含まれていて、PATH という名前で値が $PATH:/usr/share/ant/bin の環境変数を取得した場合、/usr/local/sbin:/usr/local/bin はリテラル値 $PATH:/usr/share/ant/bin に置き換えられます。

CODEBUILD_ で始まる名前の環境変数は保存しないでください。このプレフィックスは内部使用のために予約されています。

同じ名前の環境変数が複数の場所で定義されている場合は、その値は次のように決定されます。

env/secrets-manager

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

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

<key>

(必須) ローカル環境変数の名前。この名前を使用して、ビルド中に変数にアクセスします。

<secret-id>

(必須)シークレットの一意の識別子として機能する名前または Amazon リソースネーム (ARN) です。AWS アカウントのシークレットにアクセスするには、シークレット名を指定します。別の AWS アカウントのシークレットにアクセスするには、シークレット ARN を指定します。

<json-key>

(任意)値を取得するSecrets Manager のキーと値のペアのキー名を指定します。指定しない場合、json-key場合、CodeBuild はシークレットテキスト全体を取得します。

<version-stage>

(任意)バージョンに添付されているステージングラベルによって取得するシークレットのバージョンを指定します。ステージングラベルは、ローテーション処理中にさまざまなバージョンを追跡するために使用されます。version-stage を使用する場合は、version-id を指定しないでください。バージョンステージもバージョン ID も指定しない場合、デフォルトでは AWSCURRENT のバージョンステージ値でバージョンが取得されます。

<version-id>

(任意)使用するシークレットのバージョンの固有 ID を指定します。version-id を指定した場合は、version-stage を指定しないでください。バージョンステージもバージョン ID も指定しない場合、デフォルトでは AWSCURRENT のバージョンステージ値でバージョンが取得されます。

以下の例で、TestSecretSecrets Manager に保存されているキーと値のペアの名前です。のキーTestSecretMY_SECRET_VAR。ビルド中に変数にアクセスするには、LOCAL_SECRET_VAR名前。

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

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

env/exported-variables

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

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

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

注記

以下はエクスポートできません:

  • ビルドプロジェクトで指定された Amazon EC2 Systems Manager Parameter Store シークレット。

  • ビルドプロジェクトで指定されたシークレット Secrets Manager のシークレット

  • AWS_ で始まる環境変数。

環境/git-クレデンシャルヘルパー

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

注記

git-credential-helper は、パブリック Git リポジトリの Webhook によってトリガーされるビルドではサポートされません。

proxy

オプションのシーケンス。明示的なプロキシサーバーでビルドを実行する場合、設定を表すために使用されます。詳細については、「 明示的なプロキシサーバーで CodeBuild を実行する」を参照してください。

proxy/upload-artifacts

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

proxy/logs

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

phases

必要なシーケンス。ビルドの各段階で CodeBuild が実行するコマンドを表します。

注記

buildspec バージョン 0.1 では、CodeBuild はビルド環境のデフォルトシェルの各インスタンスで各コマンドを実行します。つまり、各コマンドは他のすべてのコマンドとは独立して実行されます。したがって、デフォルトでは、以前のコマンド (ディレクトリの変更や環境変数の設定など) の状態に依存する単一のコマンドを実行することはできません。この制限を回避するには、バージョン 0.2 を使用することをお勧めします。これにより、問題が解決されます。buildspec バージョン 0.1 を使用する必要がある場合は、「ビルド環境のシェルとコマンド」のアプローチをお勧めします。

phases/*/run-as

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

phases/*/失敗時

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

  • ABORT-ビルドを中止します。

  • CONTINUE-次のフェーズに進みます。

このプロパティを指定しない場合、失敗処理は遷移フェーズに従います (ビルドフェーズの移行

phases/*/finally

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

許可されるビルドフェーズ名は次のとおりです。

phases/install

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

phases/install/runtime-versions

オプションのシーケンス。ランタイムバージョンは、Ubuntu 標準イメージ 2.0 以降および Amazon Linux 2 標準イメージ 1.0 以降でサポートされています。指定した場合、少なくとも 1 つのランタイムをこのセクションに含める必要があります。特定のバージョン、メジャーバージョンの後に.xを使用して、CodeBuild がそのメジャーバージョンを最新のマイナーバージョンで使用するように指定するか、latestを使用して、最新のメジャーバージョンとマイナーバージョン (java: openjdk11ruby: 2.6nodejs: 12.x, またはjava: latest). 数値または環境変数を使用してランタイムを指定できます。たとえば、Amazon Linux 2 標準イメージ 2.0 を使用する場合、次の例は、Java のバージョン 8、Python バージョン 3 の最新マイナーバージョン、および Ruby の環境変数に含まれるバージョンをインストールすることを指定します。詳細については、「CodeBuild によって提供されるドッカーイメージ」を参照してください。

phases: install: runtime-versions: java: corretto8 python: 3.x ruby: "$MY_RUBY_VAR"

buildspec ファイルの runtime-versions セクションで 1 つ以上のランタイムを指定できます。ランタイムが別のランタイムに依存している場合は、依存しているランタイムを buildspec ファイルで指定することもできます。buildspec ファイルでランタイムを指定しない場合、CodeBuild は、使用するイメージで使用できるデフォルトのランタイムを選択します。1 つ以上のランタイムを指定すると、CodeBuild はこれらのランタイムのみを使用します。依存関係のあるランタイムが指定されていない場合、CodeBuild は依存関係のあるランタイムの選択を試みます。

2 つの指定されたランタイムが競合する場合、ビルドは失敗します。たとえば、android: 29java: openjdk11 が矛盾するので、両方が指定されている場合は、ビルドは失敗します。

使用できるランタイムの詳細については、「」を参照してください。使用可能なランタイム

注記

指定すると、runtime-versionsセクションを開き、Ubuntu 標準イメージ 2.0 以降、または Amazon Linux 2 (AL2) 標準イメージ 1.0 以降を使用する場合に、ビルドは、警告を発行します。Skipping install of runtimes. Runtime version selection is not supported by this build image。」

phases/install/commands

オプションのシーケンス。一連のスカラーが含まれ、各スカラーは、インストール中に CodeBuild が実行する単一のコマンドを表します。CodeBuild は、最初から最後まで、各コマンドを一度に 1 つずつ、指定された順序で実行します。

phases/pre_build

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

phases/pre_build/commands

pre_build が指定されている場合は必須のシーケンスです。一連のスカラーが含まれ、各スカラーは、ビルドの前に CodeBuild が実行する単一のコマンドを表します。CodeBuild は、最初から最後まで、各コマンドを一度に 1 つずつ、指定された順序で実行します。

phases/build

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

phases/build/commands

では必須buildが指定されている場合、一連のスカラーが含まれ、各スカラーは、ビルド中に CodeBuild が実行する単一のコマンドを表します。CodeBuild は、最初から最後まで、各コマンドを一度に 1 つずつ、指定された順序で実行します。

phases/post_build

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

phases/post_build/commands

では必須post_buildが指定されている場合、一連のスカラーが含まれ、各スカラーは、ビルドの後に CodeBuild が実行する単一のコマンドを表します。CodeBuild は、最初から最後まで、各コマンドを一度に 1 つずつ、指定された順序で実行します。

reports

report-group-name-or-arn

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

reports/<report-group>/files

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

  • 1 つのファイル (例:my-test-report-file.json)。

  • サブディレクトリ内の単一のファイル (my-subdirectory/my-test-report-file.jsonmy-parent-subdirectory/my-subdirectory/my-test-report-file.json など)。

  • '**/*' はすべてのファイルを再帰的に表します。

  • my-subdirectory/*という名前のサブディレクトリ内のすべてのファイルを表します my-subdirectory.

  • my-subdirectory/**/*という名前のサブディレクトリから再帰的にすべてのファイルを表します。my-subdirectory.

reports/<report-group>/file-format

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

テストレポートテスト

CUCUMBERJSON

Cucumber JSON

JUNITXML

JUnit XML

NUNITXML

NUnit XML

NUNIT3XML

NUnit 3 XML

TESTNGXML

TestNG XML

VISUALSTUDIOTRX

Visual Studio TRX

コードカバレッジレポート

CLOVERXML

クローバーXML

COBERTURAXML

コベルチュラ XML

JACOCOXML

JaCoCo XML

SIMPLECOV

SimpleCov JSON

注記

CodeBuild は、シンプレコフではなくシンプレコフ・JSON

reports/<report-group>/base-directory

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

reports/<report-group>/discard-paths

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

artifacts

オプションのシーケンス。CodeBuild がビルド出力を見つけることができる場所、および CodeBuild が S3 出力バケットにアップロードするための準備方法に関する情報を表します。たとえば、Docker イメージを作成して Amazon ECR にプッシュしている場合、または、ソースコードでユニットテストを実行していてもビルドしていない場合、このシーケンスは必要ありません。

artifacts/files

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

  • 1 つのファイル (例:my-file.jar)。

  • サブディレクトリ内の単一のファイル (my-subdirectory/my-file.jarmy-parent-subdirectory/my-subdirectory/my-file.jar など)。

  • '**/*' はすべてのファイルを再帰的に表します。

  • my-subdirectory/*という名前のサブディレクトリ内のすべてのファイルを表します my-subdirectory.

  • my-subdirectory/**/*という名前のサブディレクトリから再帰的にすべてのファイルを表します。my-subdirectory.

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

artifacts/name

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

  • CodeBuild API を使用してビルドを作成し、overrideArtifactNameフラグがProjectArtifactsプロジェクトが更新される、プロジェクトが作成される、ビルドが開始されると、オブジェクトを。

  • CodeBuild コンソールを使用してビルドを作成します。名前がビルド仕様ファイルで指定されます。セマンティックバージョニングの有効化プロジェクトを作成または更新するとき。詳細については、「ビルドプロジェクトの作成 (コンソール)」を参照してください。

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

  • これは、アーティファクトが作成された日付が付加されたアーティファクト名の例です。

    version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: myname-$(date +%Y-%m-%d)
  • CodeBuild 環境変数を使用するアーティファクト名の例です。詳細については、「ビルド環境の環境変数」を参照してください。

    version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: myname-$AWS_REGION
  • これは、アーティファクトの作成日が付加された CodeBuild 環境変数を使用するアーティファクト名の例です。

    version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: $AWS_REGION-$(date +%Y-%m-%d)

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

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

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

artifacts/base-directory

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

  • 単一の最上位ディレクトリ (例:my-directory)。

  • 'my-directory*' my-directory で始まる名前を持つすべての最上位ディレクトリを表します。

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

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
アーティファクト/除外パス

オプションのマッピング。相対的な 1 つまたは複数のパスを表します。base-directory、CodeBuildはビルドの成果物から除外します。

アーティファクト/イネーブル-シンボリックリンク

省略可能。出力タイプがZIPは、内部シンボリックリンクを ZIP ファイルに保持するかどうかを指定します。これにはyesに設定すると、ソース内のすべての内部シンボリックリンクがアーティファクト ZIP ファイルに保持されます。

アーティファクト/s3-prefix

省略可能。アーティファクトが Amazon S3 バケットに出力され、名前空間タイプがBUILD_ID。使用した場合、バケット内の出力パスは<s3-prefix>/<build-id>/<name>.zip

artifacts/secondary-artifacts

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

注記

-artifacts/filesシーケンスは、セカンダリアーティファクトしか定義されていない場合でも、常に必要です。

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

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

cache

オプションのシーケンス。CodeBuild が S3 キャッシュバケットにキャッシュをアップロードするためにファイルを準備できる場所に関する情報を表します。プロジェクトのキャッシュタイプが No Cache の場合、このシーケンスは不要です。

cache/paths

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

  • 1 つのファイル (例:my-file.jar)。

  • サブディレクトリ内の単一のファイル (my-subdirectory/my-file.jarmy-parent-subdirectory/my-subdirectory/my-file.jar など)。

  • '**/*' はすべてのファイルを再帰的に表します。

  • my-subdirectory/*という名前のサブディレクトリ内のすべてのファイルを表します my-subdirectory.

  • my-subdirectory/**/*という名前のサブディレクトリから再帰的にすべてのファイルを表します。my-subdirectory.

重要

buildspec 宣言は有効な YAML である必要があるため、buildspec 宣言のスペースは重要です。buildspec の宣言にあるスペースの数が無効な場合、すぐにビルドが失敗する可能性があります。YAML validator を使用して、buildspec の宣言が有効な YAML かどうかをテストできます。

ビルドプロジェクトを作成または更新するときに、AWS CLI または AWS SDK を使用して buildspec を宣言する場合、buildspec は、必要な空白や改行のエスケープ文字のある、YAML 形式で表される単一の文字列でなければなりません。次のセクションに例があります。

buildspec.yml ファイルの代わりに CodeBuild または AWS CodePipeline コンソールを使用する場合は、buildフェーズのみ。上記の構文を使用する代わりに、ビルドフェーズで実行するすべてのコマンドを 1 行に記載します。複数のコマンドについては、&& で各コマンドを区切ります (例: mvn test && mvn package)。

buildspec.yml ファイルの代わりに CodeBuild または CodePipeline コンソールを使用して、ビルド環境でビルド出力アーティファクトの場所を指定することができます。上記の構文を使用する代わりに、すべての場所を 1 行に記載します。複数の場所の場合は、各場所をコンマで区切ります (例: buildspec.yml, target/my-app.jar)。

buildspec の例

buildspec.yml ファイルの例を次に示します。

version: 0.2 env: variables: JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64" parameter-store: LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword phases: install: commands: - echo Entered the install phase... - apt-get update -y - apt-get install -y maven finally: - echo This always runs even if the update or install command fails pre_build: commands: - echo Entered the pre_build phase... - docker login -u User -p $LOGIN_PASSWORD finally: - echo This always runs even if the login command fails build: commands: - echo Entered the build phase... - echo Build started on `date` - mvn install finally: - echo This always runs even if the install command fails post_build: commands: - echo Entered the post_build phase... - echo Build completed on `date` reports: arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1: files: - "**/*" base-directory: 'target/tests/reports' discard-paths: no reportGroupCucumberJson: files: - 'cucumber/target/cucumber-tests.xml' discard-paths: yes file-format: CUCUMBERJSON # default is JUNITXML artifacts: files: - target/messageUtil-1.0.jar discard-paths: yes secondary-artifacts: artifact1: files: - target/artifact-1.0.jar discard-paths: yes artifact2: files: - target/artifact-2.0.jar discard-paths: yes cache: paths: - '/root/.m2/**/*'

次に、AWS CLI または AWS SDK で使用するための、単一の文字列として表現された前述の buildspec の例を示します。

"version: 0.2\n\nenv:\n variables:\n JAVA_HOME: \"/usr/lib/jvm/java-8-openjdk-amd64\\"\n parameter-store:\n LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword\n phases:\n\n install:\n commands:\n - echo Entered the install phase...\n - apt-get update -y\n - apt-get install -y maven\n finally:\n - echo This always runs even if the update or install command fails \n pre_build:\n commands:\n - echo Entered the pre_build phase...\n - docker login -u User -p $LOGIN_PASSWORD\n finally:\n - echo This always runs even if the login command fails \n build:\n commands:\n - echo Entered the build phase...\n - echo Build started on `date`\n - mvn install\n finally:\n - echo This always runs even if the install command fails\n post_build:\n commands:\n - echo Entered the post_build phase...\n - echo Build completed on `date`\n\n reports:\n reportGroupJunitXml:\n files:\n - \"**/*\"\n base-directory: 'target/tests/reports'\n discard-paths: false\n reportGroupCucumberJson:\n files:\n - 'cucumber/target/cucumber-tests.xml'\n file-format: CUCUMBERJSON\n\nartifacts:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n secondary-artifacts:\n artifact1:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n artifact2:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n cache:\n paths:\n - '/root/.m2/**/*'"

以下に示しているコマンドの例を示します。buildフェーズで、CodeBuild コンソールまたは CodePipeline コンソールで使用できます。

echo Build started on `date` && mvn install

これらの例では:

  • JAVA_HOME のキーと /usr/lib/jvm/java-8-openjdk-amd64 の値を持つプレーンテキストのカスタム環境変数が設定されます。

  • という名前のカスタム環境変数dockerLoginPasswordAmazon EC2 Systems Manager Parameter Store に保存されたは、後でキーを使用してビルドコマンドで参照されます。LOGIN_PASSWORD

  • これらのビルドフェーズ名は変更できません。この例で実行されるコマンドは次のとおりです。apt-get update -yおよびapt-get install -y maven(Apache Mavenをインストールするため)、mvn install(ソースコードをビルド出力アーティファクトにコンパイル、テスト、パッケージ化し、ビルド出力アーティファクトを内部リポジトリにインストールする)、docker login(カスタム環境変数の値に対応するパスワードでDockerにサインインするdockerLoginPasswordAmazon EC2 Systems Manager Parameter Store で設定した)、および複数のechoコマンド。-echoのコマンドは、CodeBuild がコマンドを実行する方法と、コマンドの実行順序を示すためにここに含まれています。

  • files はビルド出力場所にアップロードするファイルを表します。この例では、CodeBuild がmessageUtil-1.0.jarmessageUtil-1.0.jar ファイルは、ビルド環境の target という名の相対ディレクトリ内にあります。discard-paths: yes が指定されたため、messageUtil-1.0.jar は直接アップロードされます (中間の target ディレクトリにはアップロードされません)。ファイル名 messageUtil-1.0.jar および相対ディレクトリ名 target は、Apache Maven がこの例のビルド出力アーティファクトを作成して保存する方法にのみ基づいています。独自のシナリオでは、これらのファイル名とディレクトリは異なります。

  • reportsは、ビルド中にレポートを生成する 2 つのレポートグループを表します。

    • arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1 は、レポートグループの ARN を指定します。テストフレームワークによって生成されたテスト結果は、 target/tests/reports ディレクトリにあります。ファイル形式は JunitXml であり、パスはテスト結果を含むファイルから削除されません。

    • reportGroupCucumberJson は、新しいレポートグループを指定します。プロジェクトの名前が my-project の場合、ビルドの実行時に my-project-reportGroupCucumberJson という名前のレポートグループが作成されます。テストフレームワークによって生成されたテスト結果は、cucumber/target/cucumber-tests.xml にあります。テストファイルの形式は、CucumberJson で、テスト結果を含むファイルからパスが削除されます。

buildspec のバージョン

次の表に、buildspec のバージョンとバージョン間の変更を示します。

バージョン 変更
0.2
  • environment_variablesenv に名称変更されました。

  • plaintextvariables に名称変更されました。

  • artifactstype プロパティは廃止されました。

  • バージョン 0.1 では、AWS CodeBuild はビルド環境のデフォルトシェルの個別のインスタンスで各ビルドコマンドを実行します。バージョン 0.2 では、CodeBuild はビルド環境のデフォルトシェルの同じインスタンスですべてのビルドコマンドを実行します。

0.1 これは、ビルド仕様形式の最初の定義です。