Google Cloud Platform を使用した GitHub (プレビュー) デプロイメント: 基本ガイド

動機と紹介

ビルド プレビューは、新しいものでも革新的なものでもありません。 Heroku はそれらを何年も前から持っていました。ただし、Google Cloud Platform 上に構築している場合は、少し難しくなります。 Google Cloud Build は、Cloud Functions、Cloud Run、Kubernetes、App Engine などへのデプロイに使用できます。Cloud Build はアプリケーションやサービスのデプロイ先がわからないため、プレビューが少し複雑になります。リポジトリに接続し、GitHub でビルド ステータスを表示する GitHub アプリがありますが、それだけです。 Heroku、Vercel、Fly などの製品で見慣れたプレビュー、コメント、または「通常の」機能はありません。

単純な HTTP リクエストを使用して、Cloud Build から GitHub Pull Request にコメントを投稿する「簡単な」方法があります。しかし、 GitHub Deployments APIを使用できるのであれば、なぜ簡単なのでしょうか。

この API を使用すると、環境を作成し、環境ごとに異なる変数を設定し、プル リクエストでビルドとデプロイのステータスを直接表示できます。 CD プラットフォームで展開が完了したら、展開ステータスに URL を追加できます。これがこの記事でやることです。

GitHub デプロイメントステータス

繰り返しますが、これを行う別の方法として、HTTP リクエストで Deployments API を直接使用する方法があります。ただし、これは難しい場合があり、GitHub で認証するためにパーソナル アクセス トークンを定義する必要があります。代わりに、GitHub Apps を使用してアプリ トークンを生成し、Deployments API と対話する小さな Node.js サービスをまとめることにしました。これにより、展開プロセスをもう少し細かく制御できるようになります。

免責事項

この記事は、Google Cloud Platform と GitHub 専用に書かれています。 Google Cloud Platform、Google Cloud Build、IAM 権限についての基本的な理解があることを前提としています。

Google Cloud Platform プロジェクトが設定されている必要があります。

GitHub デプロイヤー (Node.js および Docker)

GitHub Deployer は、GitHub App で認証され、GitHub Deployments API と対話する小さな Node.js サービスです。コマンドは事前定義されており、一部の情報を Docker イメージに組み込む必要があります。そうしないと、Cloud Build のランタイム構成が複雑になりすぎます。

Docker イメージはまだ構築されていません。自分でビルドしてレジストリにプッシュする必要があります。最適な場所は、アプリケーションのイメージも保存される Google Artifact Registry です (Container Registry は非推奨です)。

1. まだ作成していない場合は、Artifact Registry リポジトリを作成します

   
   

2. GitHub アプリを作成して組織にインストールする

   • GitHub アプリを作成する

   • 必要な権限: 「pull_requests」、「deployments」、「metadata」

     
     

3. アプリ ID ([アプリ設定] 画面から) とアプリ インストール ID ([設定] をクリックすると、URL にインストール ID が表示されます。他にどこで見つかるかわかりません) をコピーします。

   
   

4. 秘密キーを作成してダウンロードし、base64 に変換します ( base64 -i your.private-key.pem )

Docker イメージをビルドする

ソース

Cloud Build はamd64で実行されるため、x86 プラットフォーム用のイメージをビルドするにはbuildxが必要です。

docker buildx build --platform linux/amd64 . -t us-central1-docker.pkg.dev/[PROJECT]/docker/gh-deployer \

--build-arg GH_APP_ID=[GITHUB_APP_ID] \

--build-arg GH_APP_PRIVATE_KEY=[GITHUB_PRIVATE_KEY_BASE_64] \

--build-arg GH_APP_INSTALLATION_ID=[GITHUB_INSTALLATION_ID] \

--build-arg GH_OWNER=[GITHUB_ORG]

イメージをレジストリにプッシュします。

docker push us-central1-docker.pkg.dev/[PROJECT]/docker/gh-deployer

Docker イメージをローカルで実行する

docker run -it -e REPO_NAME=test -e REF=main -e ENVIRONMENT=test us-central1-docker.pkg.dev/[PROJECT]/docker/gh-deployer:latest create

必要な環境変数:

• REPO_NAME : リポジトリの名前が必要です(例: gh-deployer )
• REF : デプロイするにはブランチ、タグ、または SHAが必要でした(例: main )
• ENVIRONMENT : デプロイ先の環境が必要です(例: preview )
• TRANSIENT_ENVIRONMENT :オプション/false trueに設定すると、デプロイメントは一定時間後に削除されます
• DESCRIPTION : デプロイメントの説明(オプション)

次のコマンドが最初の引数として使用できます。

• create - 新しいデプロイメントを作成します
• pending - ビルドは保留中です
• in_progress - ビルドが進行中です
• queued - ビルドはキューに入れられています
• success - デプロイメントは成功しました
• error - 何か問題が発生しました
• failure - デプロイメントが失敗しました

Cloud Build では、現時点ではオプションが少し制限されています。初期デプロイメントを作成するには Cloud Build を開始する必要があるため、 pending状態はありません。 queuedあまり意味がないので、私たち自身の設定では次のものを使用しています。

1. gh-deployer/createコミットの一時的なデプロイメントを作成します。
2. pgh-deployer/ending
3. kaniko build を実行して、デプロイメント用の Docker イメージをビルドします。
4. ビルドが完了し、イメージがデプロイされる前のgh-deployer/in_progress
5. gh-deployer/success

繰り返しになりますが、Cloud Build ではデプロイがどこに行われるかわからないため、デプロイ URL をsuccessステップに渡す方法は 2 つあります。

1. ビルドステップで、URL を/workspace/deployer_environment_urlに書き込みます。
2. successしたら、2 番目の引数を Docker イメージに渡します

デプロイメントには Cloud Run を使用しているため、特定のプル リクエスト番号のデプロイメント URL を取得するビルド ステップは次のとおりです。

- 名前: gcr.io/google.com/cloudsdktool/cloud-sdk

 env: - PR_NUMBER=$_PR_NUMBER script: >- gcloud run services list --project [project] --filter preview-$PR_NUMBER --format "value(status.address.url)" > /workspace/deployer_environment_url

Cloud Build 構成 / Terraform

クラウドビルド.yaml

クラウドビルド.yaml

以下は、 cloudbuild.yaml構成ファイルを使用した完全な例です。構築には Kaniko を使用し、デプロイメント ターゲットとして Cloud Run を使用します。

Terraform を使用している場合は、Terraform ファイル(preview.tf)も利用できます。

GitHub アクション

Deployments API を使用すると、 deployment_statusで GitHub アクションをトリガーできます。これにより、各プレビュー ビルドで品質保証チェックやエンドツーエンドのテストなどを簡単に実行できるようになります。 success状態として渡されるenvironment_urlを使用して、各プレビューでPlaywrightを実行する例を次に示します。

劇作家QA:

 if: ${{ github.event.deployment\_status.state == 'success' }} timeout-minutes: 60 runs-on: ubuntu\-latest steps: \- uses: actions/[\[email protected\]](/cdn-cgi/l/email-protection) \- uses: actions/setup\-[\[email protected\]](/cdn-cgi/l/email-protection) with: node-version: 20 cache: 'npm' \- run: npm ci \- name: Install Playwright Browsers run: npm exec playwright install \-\-with\-deps \-y \- name: Run Playwright tests run: pnpm exec playwright test env: BASE\_URL: ${{github.event.deployment\_status.environment\_url}} \- uses: actions/upload\-[\[email protected\]](/cdn-cgi/l/email-protection) if: always() with: name: playwright\-report path: playwright\-report/ retention-days: 30

最適化

• 基本イメージgcr.io/google.com/cloudsdktool/cloud-sdkは比較的大きいです。 Cloud Run コンポーネントを使用して独自の小さな gcloud イメージを構築すると、ビルドを高速化できます。

結論

GitHub デプロイステータス 完了

GitHub プル リクエストへのコメントは、最初は簡単ですが、プル リクエストごとに複数のデプロイメントがあり、ビルドが失敗するなど、柔軟性があまりなく、維持/更新が困難です。 GitHub Deployments API は、サードパーティの CI/CD システムからデプロイメントを作成および管理するためのエレガントな方法を提供します。 GitHub Deployerを使用して、デプロイメント API との対話を合理化し、HTTP API だけでは解決できないいくつかの副作用や落とし穴に対処しようとしました。

GitHub Deployments API を使用するもう 1 つの利点は、GitHub Actions のdeployment_statusトリガーを使用し、イベント ペイロードで直接environment_urlを取得できることです。

もう少し詳しいインストール/ビルド手順とすべてのコードは、 GitHub リポジトリで見つけることができます。

ご質問やコメントがございましたら、BlueSky/ Twitterにご連絡いただくか、 GitHub のディスカッションに参加してください。

こちらでも公開しております。