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.

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):

1. If not done already, create an Artifact Registry repository
2. Create a GitHub App and install it on your organization
   • Create a GitHub App
   • Required permissions: 'pull_requests', 'deployments', 'metadata'
3. 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)
4. Create & download a private key and convert it to base64 (base64 -i your.private-key.pem)

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:

• REPO_NAME: required the name of the repository (e.g. gh-deployer)
• REF: required the branch, tag or SHA to deploy (e.g. main)
• ENVIRONMENT: required the environment to deploy to (e.g. preview)
• TRANSIENT_ENVIRONMENT: optional/false if set to true, the deployment will be deleted after a certain time
• DESCRIPTION: optional a description of the deployment

The following commands are available as first argument:

• create - create a new deployment
• pending - the build is pending
• in_progress - the build is in progress
• queued - the build is queued
• success - the deployment was successful
• error - something went wrong
• failure - the deployment failed

With Cloud Build the options are currently a bit limited. There's no pending state as Cloud Build needs to start in order to create the initial deployment. queued doesn't make much sense either, so in our own setup, we're using the following:

1. gh-deployer/create to create the transient deployment for a commit
2. pgh-deployer/ending directly after create
3. Run kaniko build to build the Docker image for deployment
4. gh-deployer/in_progress after the build is done and before the image is deployed
5. gh-deployer/success after the image is deployed

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 success step:

1. In a build step, write the URL into /workspace/deployer_environment_url
2. 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 cloudbuild.yaml configuration file. We use Kaniko to build and Cloud Run as deplyoment target.

If you work with Terraform, there's a Terraform file afailable as well: preview.tf

steps:
  - name: 'us-central1-docker.pkg.dev/[project]/docker/gh-deployer:latest'
    env:
      - REPO_NAME=$REPO_NAME
      - TRANSIENT_ENVIRONMENT=true
      - DESCRIPTION=Deploying to Google Cloud Run
      - ENVIRONMENT=preview
      - REF=$REF_NAME
    args:
      - create
  - name: 'us-central1-docker.pkg.dev/[project]/docker/gh-deployer:latest'
    env:
      - REPO_NAME=$REPO_NAME
      - ENVIRONMENT=preview
      - REF=$REF_NAME
    args:
      - pending
  - name: 'gcr.io/kaniko-project/executor:latest'
    args:
      - '--destination=us-central1-docker.pkg.dev/[project]/docker/[name]:$SHORT_SHA'
      - '--use-new-run'
  - name: 'us-central1-docker.pkg.dev/[project]/docker/gh-deployer:latest'
    env:
      - REPO_NAME=$REPO_NAME
      - ENVIRONMENT=preview
      - REF=$REF_NAME
    args:
      - in_progress
  - name: gcr.io/google.com/cloudsdktool/cloud-sdk
    args:
      - run
      - deploy
      - preview-$_PR_NUMBER
      - '--image=us-central1-docker.pkg.dev/[project]/docker/[name]:$SHORT_SHA'
      - '--region=us-central1'
      - '--memory=512Mi'
      - '--platform=managed'
      - '--allow-unauthenticated'
    entrypoint: gcloud
  - 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

  - name: 'us-central1-docker.pkg.dev/[project]/docker/gh-deployer:latest'
    env:
      - REPO_NAME=$REPO_NAME
      - ENVIRONMENT=preview
      - REF=$REF_NAME
    args:
      - success

GitHub Actions

By using the Deployments API, you can trigger GitHub Actions on deployment_status. This makes it easy to run quality assurance checks, end-to-end tests etc. on each preview build. Here's an example for running Playwright on each preview using the environment_url that is passed in for the success state:

name: preview-qa

on: deployment_status

jobs:
  playwright-qa:
    if: ${{ github.event.deployment_status.state == 'success' }}
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        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-artifact@v3
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

Optimizations

• the basic image gcr.io/google.com/cloudsdktool/cloud-sdk is relatively large. You can build your own small gcloud image with Cloud Run components to speed up the builds.

Conclusion

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 GitHub Deployer 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.

Another benefit of using the GitHub Deployments API is that you can use the deployment_status trigger for GitHub Actions and get the environment_url directly with the event payload.

You can find a little more detailled installation / build instructions and all the code on the GitHub repository

If you have any questions or comments, please reach out on BlueSky / Twitter or join the discussion on GitHub.