GitHub ActionsでAWS S3 + CloudFrontに自動デプロイする方法【実体験で解説】

GitHub ActionsでAWS S3に自動デプロイする方法【結論】

GitHubにpushするだけでAWS S3 + CloudFrontへの自動デプロイを実現するには、GitHub Actionsのワークフローファイルを1つ作成するだけで完結します。

一度設定してしまえばビルド・S3アップロード・CloudFrontキャッシュ削除まですべて自動化されます。この記事ではwabi-motionの実際の構築経験をもとに、設定手順とつまずきやすいポイントをまとめて解説します。

GitHub ActionsによるAWS S3自動デプロイの仕組み

自動デプロイの流れは以下の通りです。

• ローカルでコードを修正してGitHubのmainブランチにpushする
• GitHub Actionsが自動で起動する
• ビルドコマンドを実行してサイトを生成する
• 生成されたファイルをS3にアップロードする
• CloudFrontのキャッシュを削除して最新状態を反映する

pushからサイト反映まで約30秒〜1分で完了します。手動のファイルアップロード作業が完全に不要になります。

事前準備：GitHub Actions用のIAMユーザーを作成する

GitHub ActionsからAWSを操作するには、専用のIAMユーザーとアクセスキーが必要です。AWSコンソールでIAMを開き、「ユーザーを作成」から以下の権限を持つポリシーをアタッチします。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": ["cloudfront:CreateInvalidation"],
      "Resource": "arn:aws:cloudfront::your-account-id:distribution/your-distribution-id"
    }
  ]
}

ユーザー作成後、「セキュリティ認証情報」タブからアクセスキーを作成します。シークレットアクセスキーは作成時にしか表示されないので必ず保存してください。

【セキュリティの注意点】 アクセスキーはコードに直書きせず、必ずGitHubのSecretsに登録して使用します。コードに含めてしまうとGitHubに公開された瞬間に悪用されるリスクがあります。

GitHubにAWSのシークレットを登録する

GitHubリポジトリの「Settings」→「Secrets and variables」→「Actions」から以下の4つを登録します。

• AWS_ACCESS_KEY_ID：IAMユーザーのアクセスキーID
• AWS_SECRET_ACCESS_KEY：IAMユーザーのシークレットアクセスキー
• AWS_REGION：S3バケットのリージョン（例：ap-northeast-1）
• CLOUDFRONT_DISTRIBUTION_ID：CloudFrontのディストリビューションID

【実体験メモ】 CloudFrontのディストリビューションIDはドメイン名とは別物です。CloudFrontコンソールで表示される「ID」の値（例：ABCDEFGHIJK123）を登録してください。ドメイン名を登録してしまうと後のステップでエラーになります。

GitHub Actionsのワークフローファイルを作成する

リポジトリのルートに.github/workflows/deploy.ymlを作成します。

name: Deploy to S3

on:
  push:
    branches:
      - main
  repository_dispatch:
    types:
      - microcms

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v4

      - name: Node.jsをセットアップ
        uses: actions/setup-node@v4
        with:
          node-version: '24'
          cache: 'npm'

      - name: 依存関係をインストール
        run: npm ci

      - name: ビルドを実行
        run: npm run build

      - name: AWS認証情報を設定
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ secrets.AWS_REGION }}

      - name: S3にデプロイ
        run: |
          aws s3 sync ./dist s3://your-bucket-name \
            --delete \
            --cache-control "public, max-age=31536000, immutable"

      - name: CloudFrontのキャッシュを削除
        run: |
          aws cloudfront create-invalidation \
            --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
            --paths "/*"

フレームワークによってビルドコマンドや出力ディレクトリが異なる場合は適宜変更してください。

• Astro：npm run build → ./dist
• Next.js（静的エクスポート）：npm run build → ./out
• Vue.js：npm run build → ./dist

【実体験メモ】 Node.jsは'20'ではなく'24'を指定することをおすすめします。Node.js 20はGitHub Actionsで非推奨になっており警告が出ます。

microCMSのWebhookとGitHub Actionsを連携する

ヘッドレスCMSで記事を公開したタイミングでも自動デプロイを実行したい場合は、Webhookとrepository_dispatchトリガーを組み合わせます。ワークフローにはすでにrepository_dispatchトリガーを追加しています。

microCMS側の設定手順は以下の通りです。

• GitHubでPersonal Access Token（PAT）を発行する（scopeはworkflowを選択）
• microCMS API設定 → Webhook → 「+追加」をクリックする
• GitHubトークン・ユーザー名・リポジトリ名を入力する
• トリガーイベント名に「microcms」と入力する
• 通知タイミング：コンテンツの公開時・更新時を選択する

【実体験メモ】 Webhookを設定してもGitHub Actionsが起動しない場合は、deploy.ymlにrepository_dispatchトリガーが記述されているか確認してください。ymlを修正したらmainブランチにpushして反映させる必要があります。

GitHub Actions自動デプロイのセキュリティで押さえるべき3つのポイント

自動デプロイの仕組みを導入する際にセキュリティも合わせて確認しておきましょう。

• IAMは最小権限で作成する：S3とCloudFrontの操作に必要な権限だけを付与します。AdministratorAccessのような広すぎる権限は避けましょう
• アクセスキーはGitHub Secretsにのみ保存する：コードや設定ファイルへの直書きは絶対に避けます
• 長期的にはOIDCへの移行を検討する：OIDC（OpenID Connect）を使うとアクセスキー自体が不要になります。セキュリティ面でより安全な方式です

デプロイが失敗したときの確認手順

ワークフローが失敗した場合はGitHubの「Actions」タブからログを確認します。

• 認証エラー：Secretsの登録内容にスペースや改行が混入していないか確認する
• S3アクセス拒否（AccessDenied）：IAMポリシーのバケット名やARNが正しいか確認する
• ビルドエラー：ローカルでnpm run buildを実行してエラーを再現・修正する
• CloudFrontエラー：SecretsのCLOUDFRONT_DISTRIBUTION_IDがIDになっているか確認する（ドメイン名ではない）

まとめ

GitHub ActionsによるAWS S3への自動デプロイを設定することで、pushだけでサイトが更新される開発体験を実現できました。

実際に構築してみて詰まりやすかったのはCloudFrontのディストリビューションIDの登録ミスとNode.jsのバージョン指定の2点でした。どちらもActionsのログを確認すればすぐに原因が特定できます。AWS初心者でもAIを活用しながら進めることで十分に実装可能です。セキュリティ面ではアクセスキーの権限を最小限にすることとコードへの直書きを絶対に避けることを徹底しておけば問題ありません。

よくある質問

Q. GitHub ActionsでAWS S3に自動デプロイするのは難しいですか？

ワークフローファイルを1つ作成するだけなので難易度は高くありません。IAMユーザーの作成とGitHub Secretsへの登録が完了すれば、あとはymlファイルをpushするだけで動き始めます。

Q. プライベートリポジトリでも無料で使えますか？

GitHub Actionsはプライベートリポジトリでも月2,000分まで無料です。静的サイトのビルド&デプロイは1〜3分で完了するため、個人利用であれば無料枠で十分まかなえます。

Q. microCMS以外のCMSでもWebhook連携できますか？

repository_dispatchトリガーはGitHubのAPIを叩ける外部サービスであれば対応可能です。ContentfulやSanityなど他のヘッドレスCMSでも同様の設定で連携できます。