Motivation and Introduction Build previews aren't anything new or innovative. Heroku had them for years. If you're building on Google Cloud Platform however, things are a little more difficult. Google Cloud Build can be used to deploy to Cloud Functions, Cloud Run, Kubernetes, App Engine etc. etc. This is what makes previews slightly complicated, as Cloud Build doesn't know where you're deploying your application or service to. They have a GitHub App to connect the repositories and show the build status in GitHub, but that's it. No previews, comments or any of the "normal" stuff we're used to from products like Heroku, Vercel or Fly. There's an "easy" way to post a comment on a GitHub Pull Request from Cloud Build with a simple HTTP request. But why easy when you can use the . GitHub Deployments API With this API, you can create Environments, have different variables per environment and show build & deployment status directly on a Pull Request. And once the deployment is done on your CD platform, you can add the URL to the deployment status. This is what we're going to do in this article. GitHub Deployment Status Again, there's another way of doing this by using the Deployments API directly with HTTP requests. This can be tricky sometimes though and you'll need to define a Personal Access Token to authenticate with GitHub. Instead, we decided to put together a little Node.js service that uses GitHub Apps to generate an app token and interact with the Deployments API. This allows a little finer control over the deployment process. Disclaimer This article is exclusively written for Google Cloud Platform and GitHub. Basic understanding of Google Cloud Platform, Google Cloud Build and IAM permissions is assumed. You should have a Google Cloud Platform project set up. GitHub Deployer (Node.js & Docker) GitHub Deployer is a tiny Node.js service that authorized with a GitHub App and interacts with the GitHub Deployments API. Commands are predefined and some information needs to be built in to the Docker image, as otherwise the runtime configuration in Cloud Build would get too complex. The Docker image is not ready built; you'll need to build it yourself and push it to your registry. The best place is Google Artifact Registry where the images for your application are stored as well (Container Registry is deprecated): If not done already, create an Artifact Registry repository Create a GitHub App and install it on your organization Create a GitHub App Required permissions: 'pull_requests', 'deployments', 'metadata' Copy the App ID (from the App Settings screen), and the App Installation ID (after clicking "Configure" you'll find the installation ID in the URL. No idea where else that can be found) Create & download a private key and convert it to base64 ( ) base64 -i your.private-key.pem Build the Docker image Source Cloud Build runs on , so we need to build the image for the x86 platform: amd64 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] Push the image to your registry: docker push us-central1-docker.pkg.dev/[PROJECT]/docker/gh-deployer Run the Docker image locally docker run -it -e REPO_NAME=test -e REF=main -e ENVIRONMENT=test us-central1-docker.pkg.dev/[PROJECT]/docker/gh-deployer:latest create Required environment variables: : the name of the repository (e.g. ) REPO_NAME required gh-deployer : the branch, tag or SHA to deploy (e.g. ) REF required main : the environment to deploy to (e.g. ) ENVIRONMENT required preview : if set to , the deployment will be deleted after a certain time TRANSIENT_ENVIRONMENT optional/false true : a description of the deployment DESCRIPTION optional The following commands are available as first argument: - create a new deployment create - the build is pending pending - the build is in progress in_progress - the build is queued queued - the deployment was successful success - something went wrong error - the deployment failed failure With Cloud Build the options are currently a bit limited. There's no state as Cloud Build needs to start in order to create the initial deployment. doesn't make much sense either, so in our own setup, we're using the following: pending queued to create the transient deployment for a commit gh-deployer/create directly after create pgh-deployer/ending Run kaniko build to build the Docker image for deployment after the build is done and before the image is deployed gh-deployer/in_progress after the image is deployed gh-deployer/success Again, with Cloud Build we don't know where the deployment is going to be, so there are two ways to pass the deployment URL to the step: success In a build step, write the URL into /workspace/deployer_environment_url Pass a second argument to the Docker image after success We use Cloud Run for our deployments, so here's the build step to retrieve the deployment URL for a given Pull Request number: - name: 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 Configuration / Terraform cloudbuild.yaml cloudbuild.yaml Here's a complete exmaple using the configuration file. We use Kaniko to build and Cloud Run as deplyoment target. cloudbuild.yaml If you work with Terraform, there's a Terraform file afailable as well: preview.tf GitHub Actions By using the Deployments API, you can trigger GitHub Actions on . This makes it easy to run quality assurance checks, end-to-end tests etc. on each preview build. Here's an example for running on each preview using the that is passed in for the state: deployment_status Playwright environment_url success 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 Optimizations the basic image is relatively large. You can to speed up the builds. gcr.io/google.com/cloudsdktool/cloud-sdk build your own small gcloud image with Cloud Run components Conclusion GitHub Deployment Status Done Comments on GitHub Pull Requests are easy at first, but when you have multiple deployments per Pull Request, failing builds etc. they don't offer a lot of flexibility and are hard to maintain / update. The GitHub Deployments API offers an elegant way to create and manage deployments from any third party CI/CD system. With the we tried to streamline the interaction with the deployments API and take care of some side effects or pitfalls that are impossible to solve with just the HTTP API. GitHub Deployer Another benefit of using the GitHub Deployments API is that you can use the trigger for GitHub Actions and get the directly with the event payload. deployment_status environment_url You can find a little more detailled installation / build instructions and all the code on the GitHub repository , please / or . If you have any questions or comments reach out on BlueSky Twitter join the discussion on GitHub Also published here.

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Read My Stories

Too Long; Didn't Read

Let Your Engineers & PMs focus on Product. Apply for $50K Credits!

GitHub (Preview) Deployments with Google Cloud Platform: An Essential Guide

Too Long; Didn't Read

@patrickheneise

Credibility

RELATED STORIES