メニュー
コンソールにサインインする
AWS CodeBuild
ユーザーガイド (API バージョン 2016-10-06)

AWS ドキュメント » AWS CodeBuild » ユーザーガイド » AWS CodeBuild のビルドを計画する » AWS CodeBuild のビルド仕様に関するリファレンス

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

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

ビルドスペックのファイル名とストレージの場所

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

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

  • 同じリポジトリ内の異なるビルドに、buildspec_debug.yml や buildspec_release.yml などの異なるビルドスペックファイルを使用する。

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

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

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

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

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

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

ビルドスペックの構文

ビルドスペックは YAML 形式で表現する必要があります。

ビルドスペックの構文は次のとおりです。

version: 0.2

env:
  variables:
    key: "value"
    key: "value"
  parameter-store:
    key: "value"
    key: "value"
            
phases:
  install:
    commands:
      - command
      - command
  pre_build:
    commands:
      - command
      - command
  build:
    commands:
      - command
      - command
  post_build:
    commands:
      - command
      - command
artifacts:
  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_VAR という名前で値が my_value の環境変数がすでに含まれていて、MY_VAR という名前で値が other_value の環境変数を設定した場合は、other_value が my_value に置き換わります。同様に、Docker イメージに PATH という名前で値が /usr/local/sbin:/usr/local/bin の環境変数がすでに含まれていて、PATH という名前で値が $PATH:/usr/share/ant/bin の環境変数を設定した場合は、リテラル値 $PATH:/usr/share/ant/bin が /usr/local/sbin:/usr/local/bin に置き換わります。

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

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

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

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

      • ビルドスペック宣言の値の優先順位が最も低くなります。

    • parameter-store: env が指定されていて、Amazon EC2 Systems Manager パラメータストアに保存されているカスタム環境変数を取得する場合は必須です。キーと値のスカラーのマッピングを含み、各マッピングは Amazon EC2 Systems Manager パラメータストアに保存されている 1 つのカスタム環境変数を表します。キー は、後でビルドコマンドで使用するこのカスタム環境変数を参照する名前で、値 は 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_value は other_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_build、build、および post_build フェーズの中のコマンドのいずれも、そのビルドのライフサイクルでは実行されません。詳細については、「ビルドフェーズの移行」を参照してください。

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

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

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

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

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

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

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

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

    • 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

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

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

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

      • サブディレクトリ内の単一のファイル (my-subdirectory/my-file.jar や my-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
  pre_build:
    commands:
      - echo Entered the pre_build phase...
      - docker login –u User –p $LOGIN_PASSWORD
  build:
    commands:
      - echo Entered the build phase...
      - echo Build started on `date`
      - mvn install
  post_build:
    commands:
      - echo Entered the post_build phase...
      - echo Build completed on `date`
artifacts:
  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 -y と apt-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_variables が env に名称変更されました。plaintext が variables に名称変更されました。

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

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