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

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

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

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

デフォルトの buildspec ファイルの名前と場所を変更することができます。たとえば、次のようにすることができます。

• 同じリポジトリ内の異なるビルドに、buildspec_debug.yml や buildspec_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 の値を、組み込みの環境変数 CODEBUILD_SRC_DIR の値を基準にした代替 buildspec ファイルのパスに設定します。また、AWS SDK の create project オペレーションで同等の処理を行うこともできます。詳細については、「ビルドプロジェクトの作成」または「ビルドプロジェクトの設定の変更」を参照してください。

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

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

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:
  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

phases:
  install:
    run-as: Linux-user-name
    runtime-versions:
      runtime: version
      runtime: version
    commands:
      - command
      - command
    finally:
      - command
      - command
  pre_build:
    run-as: Linux-user-name
    commands:
      - command
      - command
    finally:
      - command
      - command
  build:
    run-as: Linux-user-name
    commands:
      - command
      - command
    finally:
      - command
      - command
  post_build:
    run-as: Linux-user-name
    commands:
      - command
      - command
    finally:
      - command
      - command
reports:
  report-group-name-or-arn:
    files:
      - location
      - location
    base-directory: location
    discard-paths: no | yes
    file-format: JunitXml | NunitXml | CucumberJson | VisualStudioTrx | TestNGXml
artifacts:
  files:
    - location
    - location
  name: artifact-name
  discard-paths: no | yes
  base-directory: location
  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 ログでは次の情報が非表示になっています。

• AWS アクセスキー ID。詳細については、AWS Identity and Access Management ユーザーガイドの「IAM ユーザーのアクセスキーの管理」を参照してください。

• パラメータストアを使用して指定された文字列。詳細については、『Amazon EC2 Systems Manager ユーザーガイド』の「Systems Manager パラメータストア」および「Systems Manager パラメータストアコンソールのチュートリアル」を参照してください。

• AWS Secrets Manager を使用して指定された文字列。詳細については、「キーの管理」を参照してください。

env/variables

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

重要

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

既存の環境変数は、設定した環境変数によって置き換えられます。たとえば、Docker イメージに my_value の値を持つ MY_VAR という名前の環境変数が既に含まれていて、other_value の値を持つ MY_VAR という名前の環境変数を設定した場合、my_value が other_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_ で始まる名前の環境変数は設定しないでください。このプレフィックスは内部使用のために予約されています。

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

• ビルド開始オペレーション呼び出しの値が最も優先順位が高くなります。ビルドの作成時に環境変数を追加または上書きできます。詳細については、「AWS CodeBuild でのビルドの実行」を参照してください。

• ビルドプロジェクト定義の値が次に優先されます。プロジェクトを作成または編集するときに、プロジェクトレベルで環境変数を追加できます。詳細については、「AWS CodeBuild でのビルドプロジェクトの作成」および「AWS CodeBuild でのビルドプロジェクトの設定の変更 」を参照してください。

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

env/parameter-store

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

重要

CodeBuild が Amazon EC2 Systems Manager パラメータストアに保存されているカスタム環境変数を取得するには、CodeBuild サービスロールに ssm:GetParameters アクションを追加する必要があります。詳細については、「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_ で始まる名前の環境変数は保存しないでください。このプレフィックスは内部使用のために予約されています。

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

• ビルド開始オペレーション呼び出しの値が最も優先順位が高くなります。ビルドの作成時に環境変数を追加または上書きできます。詳細については、「AWS CodeBuild でのビルドの実行」を参照してください。

• ビルドプロジェクト定義の値が次に優先されます。プロジェクトを作成または編集するときに、プロジェクトレベルで環境変数を追加できます。詳細については、「AWS CodeBuild でのビルドプロジェクトの作成」および「AWS CodeBuild でのビルドプロジェクトの設定の変更 」を参照してください。

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

env/secrets-manager

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

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

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

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

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

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

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

env/exported-variables

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

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

注記

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

• ビルドプロジェクトで指定された Amazon EC2 Systems Manager パラメータストアシークレット

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

• AWS_ で始まる環境変数。

env/git-credential-help

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

注記

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

proxy

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

proxy/upload-artifacts

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

proxy/logs

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

phases

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

注記

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

phases/*/run-as

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

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

phases/install

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

phases/install/runtime-versions

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

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: 29 と java: openjdk11 が矛盾するので、両方が指定されている場合は、ビルドは失敗します。

以下のサポートされているランタイムを指定できます。

Ubuntu 18.04 および Amazon Linux 2 プラットフォームランタイム
ランタイム名	バージョン	特定のバージョン	特定のメジャーバージョンと最新のマイナーバージョン	最新バージョン	イメージ
android	28	android: 28	android: 28.x	android: latest	Amazon Linux 2 standard:2.0 Amazon Linux 2 standard:3.0 すべての Ubuntu 18.04 イメージ
	29	android: 29	android: 29.x	android: latest	Amazon Linux 2 standard:2.0 Amazon Linux 2 standard:3.0 すべての Ubuntu 18.04 イメージ
dotnet	3.0	dotnet: 3.0	dotnet: 3.x	dotnet: latest	Amazon Linux 2 standard:2.0 Ubuntu standard:3.0
	3.1	dotnet: 3.1	dotnet: 3.x	dotnet: latest	Amazon Linux 2 standard:3.0 Ubuntu standard:4.0
Golang	1.12	golang: 1.12	golang: 1.x	golang: latest	すべての Amazon Linux 2 イメージ すべての Ubuntu 18.04 イメージ
	1.13	golang: 1.13	golang: 1.x	golang: latest	すべての Amazon Linux 2 イメージ すべての Ubuntu 18.04 イメージ
	1.14	golang: 1.14	golang: 1.x	golang: latest	Amazon Linux 2 standard:3.0 Ubuntu standard:4.0
NodeJS	8	nodejs: 8	nodejs: 8.x	nodejs: latest	Amazon Linux 2 Standard:1.0 Ubuntu standard:2.0
	10	nodejs: 10	nodejs: 10.x	nodejs: latest	すべての Amazon Linux 2 イメージ すべての Ubuntu 18.04 イメージ
	12	nodejs: 12	nodejs: 12.x	nodejs: latest	すべての Amazon Linux 2 イメージ Ubuntu standard:3.0 Ubuntu standard:4.0
java	openjdk8	java: openjdk8	java: openjdk8.x	java: latest	Ubuntu standard:2.0 Ubuntu standard:3.0
	openjdk11	java: openjdk11	java: openjdk11.x	java: latest	Ubuntu standard:2.0 Ubuntu standard:3.0
	corretto8	java: corretto8	java: corretto8.x	java: latest	Amazon Linux 2 standard:2.0 Amazon Linux 2 standard:3.0 Ubuntu standard:4.0
	corretto11	java: corretto11	java: corretto11.x	java: latest	Amazon Linux 2 standard:2.0 Amazon Linux 2 standard:3.0 Ubuntu standard:4.0
php	73	php: 7.3	php: 7.x	php: latest	すべての Amazon Linux 2 イメージ すべての Ubuntu 18.04 イメージ
	7.4	php: 7.4	php: 7.x	php: latest	Amazon Linux 2 standard:3.0 Ubuntu standard:4.0
python	37	python: 3.7	python: 3.x	python: latest	Amazon Linux 2 standard:3.0 Amazon Linux 2 aarch64:1.0 Ubuntu standard:2.0 Ubuntu standard:4.0
	3.8	python: 3.8	python: 3.x	python: latest	Amazon Linux 2 standard:2.0 Amazon Linux 2 standard:3.0 Ubuntu standard:3.0 Ubuntu standard:4.0
ruby	2.6	ruby: 2.6	ruby: 2.x	ruby: latest	すべての Amazon Linux 2 イメージ すべての Ubuntu 18.04 イメージ
	2.7	ruby: 2.7	ruby: 2.x	ruby: latest	Amazon Linux 2 standard:3.0 Ubuntu standard:4.0

注記

runtime-versions セクションを指定して、Ubuntu Standard Image 2.0 以降、または Amazon Linux 2 (AL2) Standard Image 1.0 以降以外のイメージを使用すると、ビルドは警告「Skipping install of runtimes. Runtime version selection is not supported by this build image。」を出します。

phases/install/commands

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

phases/install/finally

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

phases/pre_build

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

phases/pre_build/commands

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

phases/pre_build/finally

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

phases/build

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

phases/build/commands

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

phases/build/finally

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

phases/post_build

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

phases/post_build/commands

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

phases/post_build/finally

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

重要

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

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.json や my-parent-subdirectory/my-subdirectory/my-test-report-file.json など)。

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

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

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

reports/<report-group>/file-format

オプションのマッピング。テストファイル形式を表します。指定しない場合は、JunitXml を使用します。有効な値は以下のとおりです。

• CucumberJson

• JunitXml

• NunitXml

• TestNGXml

• VisualStudioTrx

reports/<report-group>/base-directory

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

reports/<report-group>/discard-paths

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

アーティファクト

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

artifacts/files

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

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

artifacts/name

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

• CodeBuild API を使用してビルドを作成する場合に、プロジェクトの更新、プロジェクトの作成、またはビルドの開始時に、ProjectArtifacts オブジェクトで overrideArtifactName フラグを設定する。

• CodeBuild コンソールを使用してビルドを作成する場合に、buildspec ファイルで名前を指定し、プロジェクトの作成または更新時に [Enable semantic versioning (セマンティックバージョニングを有効にする)」を選択する。詳細については、「ビルドプロジェクトの作成 (コンソール)」を参照してください。

ビルド時に計算される 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) 

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

artifacts/secondary-artifacts

オプションのシーケンス。アーティファクト識別子とアーティファクト定義との間のマッピングとしての 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:
  secondary-artifacts:
    artifact1:
      files:
        - directory/file
      name: secondary-artifact-name-1
    artifact2:
      files:
        - directory/file2
      name: secondary-artifact-name-2

キャッシュ

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

cache/paths

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

重要

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/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 で使用するための、単一の文字列として表現された前述の 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/**/*'"

CodeBuild または 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 コマンドは、CodeBuild がコマンドを実行する方法と、コマンドの実行順序を示すためにここに含まれています。

• files はビルド出力場所にアップロードするファイルを表します。この例では、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 がこの例のビルド出力アーティファクトを作成して保存する方法にのみ基づいています。独自のシナリオでは、これらのファイル名とディレクトリは異なります。

• 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 のバージョンとバージョン間の変更を示します。

Version	変更
0.2	environment_variables が env に名称変更されました。 plaintext が variables に名称変更されました。 artifacts の type プロパティは廃止されました。 バージョン 0.1 では、AWS CodeBuild はビルド環境のデフォルトシェルの個別のインスタンスで各ビルドコマンドを実行します。バージョン 0.2 では、CodeBuild はビルド環境のデフォルトシェルの同じインスタンスですべてのビルドコマンドを実行します。
0.1	これは、ビルド仕様形式の最初の定義です。