AWS CodeBuild buildspec入門 - ビルド設定ファイルの基本をやさしく解説 ​

CodeBuildでビルド処理を自動化するには、buildspec.ymlという設定ファイルが必要です。このファイルの基本的な書き方から、実際のプロジェクトで使える設定まで、初心者向けにやさしく解説します。

buildspec.ymlとは何か ​

ビルド設定ファイルの役割 ​

buildspec.ymlは、「CodeBuildにビルドの手順を教える設計書」です。人間がパソコンでアプリを作るときの手順を、自動化システムが理解できる形で記述します。

ファイルの配置場所 ​

buildspec.ymlファイルは、通常プロジェクトのルートフォルダ（一番上の階層）に置きます。GitHubやCodeCommitのリポジトリで言うと、README.mdと同じ場所になります。

buildspec.ymlの基本構造 ​

最もシンプルな例 ​

まずは最小限の設定から見てみましょう。

yaml
version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 18
  build:
    commands:
      - npm install
      - npm run build

artifacts:
  files:
    - '**/*'
  base-directory: dist

この例では以下のことが起こります：

  1. Node.js 18をインストール
  2. npm installで依存関係をインストール
  3. npm run buildでアプリをビルド
  4. distフォルダの内容を成果物として保存

各セクションの意味 ​

version（バージョン） ​

yaml
version: 0.2  # 現在推奨されているバージョン

buildspec.ymlの書式バージョンを指定します。現在は「0.2」が最新です。

phases（フェーズ） ​

ビルド処理を段階的に分けて実行する部分です。料理のレシピのように、順番に実行されます。

artifacts（成果物） ​

ビルドで作成されたファイルのうち、保存したいものを指定します。

yaml
artifacts:
  files:
    - '**/*'        # すべてのファイル
  base-directory: dist  # distフォルダの中身を保存

言語別の基本設定例 ​

Web開発（Node.js + React）の場合 ​

yaml
version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 18
    commands:
      - echo "Node.jsプロジェクトのビルド開始"
      
  pre_build:
    commands:
      - npm install
      - npm test
      
  build:
    commands:
      - npm run build
      
  post_build:
    commands:
      - echo "ビルド完了"

artifacts:
  files:
    - '**/*'
  base-directory: build

サーバーアプリ（Java + Spring Boot）の場合 ​

yaml
version: 0.2

phases:
  install:
    runtime-versions:
      java: corretto17
    commands:
      - echo "Javaプロジェクトのビルド開始"
      
  pre_build:
    commands:
      - mvn test
      
  build:
    commands:
      - mvn package -DskipTests
      
artifacts:
  files:
    - target/*.jar

よく使われる便利機能 ​

環境変数の設定 ​

開発環境と本番環境で異なる設定値を使いたい場合に活用します。

yaml
version: 0.2

env:
  variables:
    NODE_ENV: production
    APP_VERSION: "1.0.0"
    
phases:
  build:
    commands:
      - echo "環境: $NODE_ENV"
      - echo "バージョン: $APP_VERSION"  
      - npm run build

機密情報の安全な管理 ​

パスワードやAPIキーなどの機密情報は、buildspec.ymlに直接書かずに、AWSの専用サービスから取得します。

yaml
env:
  secrets-manager:
    DB_PASSWORD: myapp-secrets:database_password
  parameter-store:
    API_URL: /myapp/api/url

キャッシュ機能でビルド時間短縮 ​

一度ダウンロードした依存関係ファイルを保存しておき、次回のビルドで再利用する機能です。

yaml
version: 0.2

cache:
  paths:
    - 'node_modules/**/*'  # npmパッケージをキャッシュ
    
phases:
  pre_build:
    commands:
      - npm install  # 初回は時間がかかる、2回目以降は高速

キャッシュの効果:

  • 初回ビルド: 5分
  • 2回目以降: 2分（依存関係ダウンロード時間を短縮）

テストとビルドの組み合わせ ​

品質チェック付きビルドの例 ​

yaml
version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 18
      
  pre_build:
    commands:
      - npm install
      - npm run test      # テスト実行
      - npm run lint      # コード品質チェック
      
  build:
    commands:
      - npm run build     # テスト成功時のみ実行される
      
artifacts:
  files:
    - '**/*'
  base-directory: dist

実際の使用場面 ​

Webサイトの自動デプロイ ​

例えば、ブログサイトやコーポレートサイトを更新する際の自動化に使えます。

APIアプリの自動テスト・デプロイ ​

yaml
version: 0.2

phases:
  install:
    runtime-versions:
      python: 3.9
      
  pre_build:
    commands:
      - pip install -r requirements.txt
      - python -m pytest tests/  # テスト実行
      
  build:
    commands:
      - echo "APIサーバーのパッケージ作成中"
      - python setup.py bdist_wheel
      
artifacts:
  files:
    - dist/*.whl

トラブル対応のコツ ​

よくあるエラーと対処法 ​

1. ランタイムが見つからない ​

エラー: Runtime version 'nodejs: 20' is not supported

原因: 指定したランタイムバージョンがCodeBuildでサポートされていない

対処法: サポートされているバージョンに変更

yaml
runtime-versions:
  nodejs: 18  # 20ではなく18を使用

2. ビルドが途中で止まる ​

エラー: コマンドがエラーで終了

対処法: エラー詳細を確認できるよう、echoを追加

yaml
build:
  commands:
    - echo "ビルド開始"
    - npm run build
    - echo "ビルド完了"

デバッグに便利な設定 ​

yaml
phases:
  install:
    commands:
      - echo "=== 環境情報 ==="
      - node --version
      - npm --version
      - pwd
      - ls -la

これらの基本的な理解により、自分のプロジェクトに合わせたbuildspec.ymlを作成できるようになります。まずは簡単な設定から始めて、徐々に機能を追加していくのがおすすめです。