Amplify Hosting を CloudFormation で展開しようとしてハマった話

はじめに

こんにちは、ほうき星です。

皆さんは　Amplify Hosting を利用していますでしょうか？
Next.js等のアプリケーションをサーバレスにデプロイすることができ、私は重宝しています。

Amplify Hosting はマネジメントコンソールから簡単に作成できますが、他の AWS リソースを合わせて構築する場合、IaC 化したくなると思います。
私も Amplify Hosting を CloudFormation で展開したくなったのですが、思わぬ落とし穴がありましたので共有します。

GitHub アプリを介した Amplify Hosting のデプロイ

Amplify Hosting を利用してアプリをホストする際、GitHub 等のリポジトリに接続する必要があります。
GitHub への接続には OAuth を利用した方法と Amplify GitHub アプリ を利用した方法の2つがあり、現在は後者の Amplify GitHub アプリを利用した方法でのアクセスが推奨されています。

GitHub リポジトリに保存されている新しいアプリに接続すると、デフォルトでは Amplify は GitHub アプリを使用してリポジトリにアクセスします。ただし、以前に GitHub リポジトリから接続した既存の Amplify アプリは、アクセスに OAuth を使用します。CI/CD はこれらのアプリでも引き続き機能しますが、新しい Amplify GitHub アプリを使用するように移行することを強くお勧めします。

Amplify GitHub アプリのインストール

Amplify GitHub アプリのインストールはマネジメントコンソールより行います。
詳細は以下ドキュメントの通りです。

ハマった点

公式ドキュメントには CloudFormation 等を使用して　Amplify GitHub アプリ接続を使用した Amplify Hosting の構築方法が記載されています。

GitHub アカウントで個人アクセストークンを生成する

1. GitHub アカウントにサインインします。
2. 右上隅にあるプロフィール写真を探し、メニューから [設定] を選択します。
3. 左側のナビゲーションメニューから、[デベロッパー設定] を選択します。
4. 「GitHub アプリ」ページの左側のナビゲーションメニューで、[個人アクセストークン] を選択します。
5. 「個人アクセストークン」ページで、[新規トークンを生成] を選択します。
6. 「新規個人アクセストークン」ページの「メモ」に、トークンのわかりやすい名前を入力します。
7. 「スコープの選択」セクションで、「admin: repo_hook」を選択します。
8. [Generate token] を選択します。
9. 個人アクセストークンをコピーして保存します。CLI、または SDKs を使用して Amplify アプリをデプロイする> ときに AWS CloudFormation、これを提供する必要があります。

Amplify GitHub アプリが GitHub アカウントにインストールされ、個人用アクセストークンを生成したら、Amplify CLI AWS CloudFormationまたは SDKs を使用して新しいアプリをデプロイできます。accessToken フィールドを使用して、前の手順で作成した個人アクセストークンを指定します。
詳細については、Amplify API リファレンスの「CreateApp」と、ユーザーガイドAWS CloudFormation の「AWS:: Amplify:: App」を参照してください。

つまりCloudFormation で Amplify GitHub アプリを介してアクセスする Amplify Hosting を作成するには

• 個人アクセストークン（classic）を作成し
• admin: repo_hookを許可し
• AWS:: Amplify:: App のaccessTokenに設定する

とドキュメントに書かれています。

やってみた結果①

ドキュメントに従ってadmin: repo_hookを許可した個人アクセストークンを使用して Amplify Hosting を CloudFormation で展開しました。

ですが残念なことにレポジトリへアクセスできない旨のエラーを吐き、リソースの作成に失敗してしまいます。

Resource handler returned message: "Invalid request provided: There was an issue setting up your repository. Please try again later.({"message":"Not Found","documentation_url":"https://docs.github.com/rest/repos/repos#get-a-repository","status":"404"}) (Service: Amplify, Status Code: 400, Request ID: ○○) (SDK Attempt Count: 1)" (RequestToken: ○○, HandlerErrorCode: InvalidRequest)

やってみた結果②

レポジトリへアクセスできない旨のエラーとなってしまったので、個人アクセストークンにおいてrepoの許可を追加してトライします。

CloudFormation 上リソースを作成することができました。

しかし、今度はGitHub への接続に Amplify GitHub アプリではなくOAuth が使用され、マネジメントコンソール上 Amplify GitHub アプリへの移行を促される状態となってしまいました。

どうすればいいのか

ドキュメント通りに個人アクセストークン（classic）を使用し、admin: repo_hookのみを許可した場合はエラーで Amplify Hosting を作成できず、追加でrepoを許可すると Amplify Hosting は作成できるものの OAuth を利用した接続になってしまうことが分かりました。

ではどうすれば Amplify GitHub アプリを利用した接続を持った Amplify Hosting を作成できるのでしょうか？

Fine-grained tokens を使用する

実は個人アクセストークンは二種類あり、ドキュメントで触れられている classic と Fine-grained tokens があります。後者はよりセキュリティを強化した位置づけのトークンで最近登場しました。
このFine-grained tokens を使用してリソースを作成したところ、Amplify GitHub アプリで接続する Amplify Hosting を作成することができました。

個人アクセストークン（Fine-grained tokens）では以下を許可しました。

• Repository access：対象のレポジトリ
• Permissions：Webhooks（Read and write）とMetadata（Read-only）

CloudFormation 上リソースを作成することができました。

マネジメントコンソール上でも移行を促す表示は出ず、Amplify GitHub アプリで接続できていることが確認できました。

さいごに

本記事では Amplify Hosting を CloudFormation で展開しようとしてハマった点とその対処をご紹介しました。
SDK等の内部実装に変更があったのかもしれませんが、ドキュメントを信じて作成しようとするとエラーに遭遇してハマるのは悲しいものがありますね...ぜひともドキュメントを更新してほしいものです。

本記事が誰かの Amplify Hosting ライフの一助になれば幸いです。