AWS CodeBuild
ユーザーガイド (API バージョン 2016-10-06)

このガイドの手順では、新しいコンソールデザインがサポートされています。古いバージョンのコンソールを選択すると、古い概念が反映され、本ガイドの基本的な手順がそのまま適用されます。新しいコンソールのヘルプにアクセスするには、情報アイコンを選択します。

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

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

ビルド仕様のファイル名とストレージの場所

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

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

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

  • config/buildspec.yml など、ソースディレクトリのルート以外の場所にビルド仕様ファイルを保存する。

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

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

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

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

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

ビルド仕様の構文

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

ビルド仕様の構文は次のとおりです。

version: 0.2 env: variables: key: "value" key: "value" parameter-store: key: "value" key: "value" phases: install: commands: - command - command finally: - command - command pre_build: commands: - command - command finally: - command - command build: commands: - command - command finally: - command - command post_build: commands: - command - command finally: - command - command artifacts: files: - location - location - name discard-paths: yes base-directory: location secondary-artifacts: artifactIdentifier: files: - location - location discard-paths: yes base-directory: location artifactIdentifier: files: - location - location discard-paths: yes base-directory: location cache: paths: - path - path

ビルド仕様には次のものが含まれています。

  • version: 必要なマッピング。ビルド仕様のバージョンを表します。0.2 を使用することをお勧めします。

    注記

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

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

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

      重要

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

      既存の環境変数は、設定した環境変数によって置き換えられます。たとえば、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_ で始まる名前の環境変数は設定しないでください。このプレフィックスは内部使用のために予約されています。

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

      • ビルド開始オペレーション呼び出しの値が最も優先順位が高くなります。

      • ビルドプロジェクト定義の値が次に優先されます。

      • ビルド仕様宣言の値の優先順位が最も低くなります。

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

      重要

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

      Amazon EC2 Systems Manager パラメータストアから取得する環境変数は、既存の環境変数を置き換えます。たとえば、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_ で始まる名前の環境変数は保存しないでください。このプレフィックスは内部使用のために予約されています。

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

      • ビルド開始オペレーション呼び出しの値が最も優先順位が高くなります。

      • ビルドプロジェクト定義の値が次に優先されます。

      • ビルド仕様宣言の値の優先順位が最も低くなります。

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

    注記

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

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

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

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

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

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

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

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

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

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

    重要

    以前のビルドフェーズのコマンドが失敗した場合、一部のビルドフェーズのコマンドが実行されないことがあります。たとえば、install フェーズ中にコマンドが失敗した場合は、pre_buildbuild、および post_build フェーズの中のコマンドのいずれも、そのビルドのライフサイクルでは実行されません。詳細については、「ビルドフェーズの移行」を参照してください。

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

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

    • files: 必要なシーケンス。ビルド環境でのビルド出力アーティファクトを含む場所を表します。スカラーのシーケンスが含まれ、各スカラーは、AWS 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 という名前のサブディレクトリから再帰的にすべてのファイルを表します。

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

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

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

      • AWS CodeBuild コンソールを使用してビルドを作成します。名前がビルド仕様ファイルで指定されます。プロジェクトを作成または更新するときに [Use the name specified in the buildspec file (ビルド仕様ファイルで指定された名前を使用する)] を選択します。詳細については、「ビルドプロジェクトの作成 (コンソール)」を参照してください。

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

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

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

      この例は、AWS CodeBuild 環境変数を使用するアーティファクト名の例です。詳細については、「ビルド環境の環境変数」を参照してください。

      version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: myname-$(AWS_REGION)

      これは、アーティファクトの作成日が付加された AWS CodeBuild 環境変数を使用するアーティファクト名の例です。

      version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: $(AWS_REGION)-$(date +%Y-%m-%d)
    • discard-paths: オプションのマッピング。ビルド出力アーティファクト内のファイルへのパスを破棄するかどうかを表します。パスを破棄する場合は yes、それ以外の場合は、no または指定しません (デフォルト)。たとえば、ビルド出力アーティファクト内のファイルへのパスは com/mycompany/app/HelloWorld.java となり、yes を指定することで、パスは HelloWorld.java だけに短縮されます。

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

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

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

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

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

      |-- my-build1 | `-- my-file1.txt `-- my-build2 |-- my-file2.txt `-- my-subdirectory `-- my-file3.txt

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

      artifacts: files: - '*/my-file3.txt' base-directory: my-build2

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

      my-subdirectory `-- my-file3.txt

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

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

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

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

      { "name": "sample-project", "secondaryArtifacts": [ { "type": "S3", "location": "output-bucket1", "artifactIdentifier": "artifact1" }, { "type": "S3", "location": "output-bucket2", "artifactIdentifier": "artifact2" } ] }

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

      version: 0.2 phases: build: commands: - echo Building... artifacts: secondary-artifacts: artifact1: files: - directory/file artifact2: files: - directory/file2
  • cache: オプションのシーケンス。AWS CodeBuild が Amazon S3 キャッシュバケットにキャッシュをアップロードするためにファイルを準備できる場所に関する情報を表します。プロジェクトのキャッシュタイプが No Cache の場合、このシーケンスは不要です。

    • paths: 必要なシーケンス。キャッシュの場所を表します。スカラーのシーケンスが含まれ、各スカラーは、AWS 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 という名前のサブディレクトリから再帰的にすべてのファイルを表します。

重要

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

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

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

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

ビルド仕様の例

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

version: 0.2 env: variables: JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64" parameter-store: LOGIN_PASSWORD: "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` artifacts: files: - target/messageUtil-1.0.jar discard-paths: yes secondary-artifacts: artifact1: files: - target/messageUtil-1.0.jar discard-paths: yes artifact2: files: - target/messageUtil-1.0.jar discard-paths: yes cache: paths: - '/root/.m2/**/*'

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

"version: 0.2\n\nenv:\n variables:\n JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64"\n parameter-store:\n LOGIN_PASSWORD: "dockerLoginPassword"\n\nphases:\n install:\n commands:\n - apt-get update -y\n - apt-get install -y maven\n pre_build:\n commands:\n - echo Entered the pre_build phase...\n build:\n commands:\n - echo Build started on `date`\n - mvn install\n post_build:\n commands:\n - echo Build completed on `date`\nartifacts:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes"

AWS CodeBuild または AWS CodePipeline コンソールで使用する build フェーズのコマンドの例を次に示します。

echo Build started on `date` && mvn install

これらの例では:

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

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

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

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

ビルド仕様のバージョン

次の表に、ビルド仕様のバージョンとバージョン間の変更を示します。

Version 変更
0.2

environment_variablesenv という名前に変更されました。plaintext の名前が variables に変更されました。

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

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