GitHub (Preview) Deployments with Google Cloud Platform
Tags: googlecloud, github, deployment, devops
Published: 2023-05-30 18:43:17

## 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](https://docs.github.com/en/rest/deployments/deployments?apiVersion=2022-11-28).

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.


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/og6avuoujif6ej957a8r.png)


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](https://docs.github.com/en/developers/apps/creating-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`)


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ze846zhcaxa3gmj7159b.png)


### Run the Docker image locally

```bash
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:

```yaml
- 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](https://github.com/zentered/gh-deployer/tree/main/cloudbuild)

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](https://github.com/zentered/gh-deployer/tree/main/terraform)

```yaml
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](https://playwright.dev/) on each preview using the `environment_url` that is passed in for the `success` state:

```yaml
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](https://cloud.google.com/sdk/docs/downloads-docker#alpine-based_images) to speed up the builds.

## Conclusion


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qlazkw7sgmx388jlpe8o.png)



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](https://github.com/zentered/gh-deployer/tree/main#github-deployer)

**If you have any questions or comments**, please [reach out on BlueSky](https://bsky.app/profile/zentered.co) / [Twitter](https://twitter.com/zenteredco) or [join the discussion on GitHub](https://github.com/zentered/feedback/discussions/).