Configuring deployment previews

Retrieving the code sample

For ease of use in this tutorial, you will create a new GitHub repository with a copy of a Hello World application based on a template. You will then add a new file to this repo with the custom Cloud Build configuration.

1. Log into GitHub and navigate to the template repo.
2. Create a new repo using this template by clicking "Use this template".
   1. Name your repo helloworld-python.
   2. Choose either "Public" or "Private" for the repo.
   3. Click Create repository from template.

3. Create a new Cloud Build configuration file in your repo (full instructions):

   1. On your repo page, click Add file > Create new file
   2. Name the new file cloudbuild.yaml

   3. Copy the code below to cloudbuild.yaml:

      run/deployment-previews/cloudbuild-configurations/cloudbuild.yaml

      View on GitHub Feedback

      steps:
        - id: "build image"
          name: "gcr.io/cloud-builders/docker"
          args: ["build", "-t", "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}", "."]
      
        - id: "push image"
          name: "gcr.io/cloud-builders/docker"
          args: ["push", "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}"]
      
        - id: "deploy prod service"
          name: "gcr.io/google.com/cloudsdktool/cloud-sdk"
          entrypoint: "gcloud"
          args:
            [
              "run",
              "deploy",
              "${_SERVICE_NAME}",
              "--platform",
              "managed",
              "--region",
              "${_REGION}",
              "--allow-unauthenticated",
              "--image",
              "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}",
            ]
      
        # Force the new revision to serve 100% of traffic.
        - id: "ensure prod service live"
          name: "gcr.io/google.com/cloudsdktool/cloud-sdk"
          entrypoint: "gcloud"
          args:
            [
              "run",
              "services",
              "update-traffic",
              "${_SERVICE_NAME}",
              "--to-latest",
              "--platform",
              "managed",
              "--region",
              "${_REGION}",
            ]
      
      substitutions:
        _SERVICE_NAME: myservice
        _REGION: us-central1

   4. Keep the default "Commit directly into the main branch" selection.

   5. Click Commit new file.

Deploying your service with a build trigger

This tutorial shows shows how to set up a build trigger to start a build automatically each time you update the main branch of your repository. You can also deploy your service manually by invoking Cloud Build each time you want to deploy a change.

For this tutorial, use the cloudbuild.yaml file to deploy a sample service called myservice.

1. Grant the Cloud Run Admin and Service Account User roles to the Cloud Build service account (full instructions):

   1. In the Cloud Console, go to the Cloud Build account settings page.

      Go to the Cloud Build account settings page

   2. Enable the Cloud Run Admin role.

   3. On the confirmation dialog, click Grant access to all service accounts.

2. Connect your GitHub account to Cloud Build (full instructions):

   1. In the Cloud Console, go to the Cloud Build triggers page.

      Go to the Cloud Build triggers page

   2. Click Connect Repository.

   3. Select GitHub (Cloud Build GitHub App) as the source, and step through the authentication and authorization dialogs.

   4. Select the "GITHUB_USER_NAME/helloworld-python" repository.

   5. Click Connect repository.

   6. In "Create a trigger (optional)", click Create a trigger.

3. Create a Cloud Build trigger (full instructions):

   1. In the Cloud Build triggers page, click Create trigger.
   2. Enter in the following details:
      • Name: prod-deploy
      • Event: Push to Branch
      • Source Repository: "GITHUB_USER_NAME/helloworld-python"
      • Source Branch: ^main$
      • Build Configuration: Cloud Build configuration file (yaml or json)
      • Cloud Build configuration file location: cloudbuild.yaml
   3. Click Create.

4. Run the new trigger manually:

   1. On the new trigger listing, click Run.
   2. In the popup, confirm the branch name (main), and click Run Trigger.
   3. Check the progress of the build by going to the Cloud Build history.
   4. Wait for the build to complete.

5. Confirm successful deployment.

   1. In the Cloud Console, go to the Cloud Run page.

      Go to the Cloud Run page

   2. Confirm that the service has a green check mark showing successful deployment.

   3. Click the Revisions tab and confirm that the service has one revision, serving 100% of traffic, starting with "myservice-00001-".

   4. Click on the service's URL and confirm that the service displays "Hello World!".

   

   

Creating tokens and configurations

The prod-deploy trigger created in the previous section deploys the service when a push is made to the main branch. You will now create a second trigger that runs whenever a pull request is created or updated in your repo.

After the new trigger is set up, the preview will be deployed, but there will be no information in the pull request to link to the preview. To set up this functionality, you need to complete the following additional configuration steps:

• Create a GitHub token
• Store this token in Secret Manager
• Create a custom image to use as a step in Cloud Build.

Creating and storing a GitHub Token

1. Create a GitHub token to allow writing back to a pull request (full instructions):
   1. Go to the GitHub Personal Access token settngs page.
   2. Click Generate new token.
   3. Enter the following details:
      • Note: preview-deploy
      • Expiration: 30 days
      • Scope:
        • For a public repo: repo:status ("Access commit status")
        • For a private repo: repo ("Full control of private repositories")
   4. Click Generate token.
   5. Copy the value of the generated token.

2. Store the GitHub token in Secret Manager:

   1. In the Cloud Console, go to the Secret Manager page.

      Go to the Secret Manager page

   2. Click Create Secret.

   3. Enter the following details:

      1. Name: github_token.
      2. Secret value: paste the token value you copied from GitHub.

   4. Click Create Secret.

3. Allow Cloud Build access to this secret:

   1. In a new browser tab, in the Cloud Console, go to the Cloud Build settings page.

      Go to the Cloud Build settings page

   2. Copy the value for "Service account email".

      • The email is PROJECT_NUM@cloudbuild.gserviceaccount.com

   3. Return to Secret Manager, and click on the Permission tab, and click addAdd

      • New Principals: PROJECT_NUM@cloudbuild.gserviceaccount.com
      • Role: Secret Manager Secret Accessor

   4. Click Save.

GitHub recommends setting expiration for personal access tokens, and will send reminder emails when tokens are set to expire. If you continue to use deployment previews, create a new version of the github_token when you regenerate your token. The builder in the next step retrieves the latest version of the token, so the previews will continue to work.

Creating a new image for Cloud Build

The script that writes the "Deployment Preview" notification to the pull request is located within the Python Docs Samples. Instead of adding this script into your source code, you can optionally build this script into a container within your project and run that container as a step in your Cloud Build configuration.

You can complete the following instructions using either Cloud Shell, or your local machine if you have installed and configured git and Google Cloud CLI. The instructions below show both methods.

1. In the Cloud Console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Cloud Console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Configure Google Cloud CLI to use your project, replacing PROJECT_ID with your project ID:

   export PROJECT_ID=PROJECT_ID
   gcloud config set project $PROJECT_ID
   

   If using Cloud Shell, you may need to authorize Google Cloud CLI to make a Google Cloud API call. Click Authorize to allow this action to proceed.
3. Create a new container image:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples
   cd python-docs-samples/
   gcloud builds submit --tag gcr.io/$PROJECT_ID/deployment-previews run/deployment-previews
   

4. Confirm that the container has been created:

   gcloud container images list
   

5. Remove the cloned repository:

   cd ..
   rm -rf python-docs-samples
   

Add the new Cloud Build configuration

Your repository already has a cloudbuild.yaml file that is used on your main branch. You will now create a new configuration for this new trigger.

1. On your GitHub repo page, click Add file > Create new file

   1. Name the new file cloudbuild-preview.yaml
   2. Copy the code below, and paste it into your new file:
   run/deployment-previews/cloudbuild-configurations/cloudbuild-preview.yaml

   View on GitHub Feedback

   steps:
     - id: "build image"
       name: "gcr.io/cloud-builders/docker"
       args:
         [
           "build",
           "-t",
           "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}:${_PR_NUMBER}-${SHORT_SHA}",
           ".",
         ]
   
     - id: "push image"
       name: "gcr.io/cloud-builders/docker"
       args:
         [
           "push",
           "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}:${_PR_NUMBER}-${SHORT_SHA}",
         ]
   
     - id: "deploy revision with tag"
       name: "gcr.io/google.com/cloudsdktool/cloud-sdk"
       entrypoint: "gcloud"
       args:
         [
           "run",
           "deploy",
           "${_SERVICE_NAME}",
           "--platform",
           "managed",
           "--region",
           "${_REGION}",
           "--image",
           "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}:${_PR_NUMBER}-${SHORT_SHA}",
           "--tag",
           "pr-${_PR_NUMBER}",
           "--no-traffic",
         ]
   
     - id: "link revision on pull request"
       name: "gcr.io/${PROJECT_ID}/deployment-previews" # our custom builder
       secretEnv: ["GITHUB_TOKEN"]
       args:
         [
           "set",
           "--project-id",
           "${PROJECT_ID}",
           "--region",
           "${_REGION}",
           "--service",
           "${_SERVICE_NAME}",
           "--pull-request",
           "${_PR_NUMBER}",
           "--repo-name",
           "${_GITHUB_REPO}",
           "--commit-sha",
           "${SHORT_SHA}",
         ]
   
   substitutions:
     _SERVICE_NAME: myservice
     _REGION: us-central1
     _GITHUB_REPO: $(pull_request.pull_request.head.repo.full_name)
   
   options:
     dynamicSubstitutions: true
   
   availableSecrets:
     secretManager:
       - versionName: projects/$PROJECT_ID/secrets/github_token/versions/latest
         env: "GITHUB_TOKEN"

2. Commit the change to the main branch of your repository.

Creating the secondary trigger

Now that all the groundwork is in place, create the new trigger.

1. Create a new Cloud Build trigger (full instructions):

   1. In the Cloud Console, go to the Cloud Build triggers page.

      Go to the Cloud Build triggers page

   2. Click Create Trigger.

   3. Enter the following details:

      • Name: preview-deploy
      • Event: Pull Request
      • Source Repository: "GITHUB_USER_NAME/helloworld-python"
      • Base branch: ^main$
      • Comment control: Required except for owners and collaborators
        • As the owner of the repo, previews will be automatically built on pull requests you create.
        • If you want to allow anyone to preview their changes, read more about the security implications of selecting "Not required".
      • Configuration: Cloud Build Configuration file
      • Cloud Build configuration file location: cloudbuild-preview.yaml

   4. Click Create.

Checking Success

Since this new trigger is fired when a new pull request is created, you will need to create a new pull request in order to test it.

1. Go to your repository, and make a visual change to app.py in a new branch.
   1. Go to app.py, and click the pencil icon (edit).

      

   2. Make a change; for example, change "Hello" to "Greetings".
   3. Select Create a new branch for this commit and start a pull request, then click Propose change.

2. Create a new pull request with this branch.

   If the trigger is configured correctly, a new check is displayed soon after you create the pull request:

   

3. The name of the check is the name of the trigger and your project ID. Check on the progress of the build by clicking Details > View more details on Google Cloud Build.

   If your trigger fails and you need to resubmit the build, or if you want to make another change to your pull request, you need to commit a change to the same branch. Each new commit on a pull request will trigger a new build.

4. After the trigger completes, a new status check named "Deployment Preview" is displayed for the pull request. The icon displayed is your avatar because your account owns the token being used:

   

5. Click Details to navigate to the preview. The URL shown is the same as your original service URL, but is prefixed with "pr-1---".

   

   Note that if you navigate to the original service URL, the original content is shown:

   

6. View the revision list for your service to check the service state in Cloud Run: there are now two revisions serving traffic: the original and the preview:

   

7. Continue making changes to the pull request by adding new commits to the branch. Each time you commit, the preview-deploy trigger fires, creating a new revision of the service and making the revision available at the same URL:

   

8. After you are ready to merge your changes, click Merge Pull Request. The original prod-deploy trigger runs, and the changes from the pull request are reflected in the original URL:

   

   The new revision serves 100% of the traffic at the main URL, but the pull request's preview URL is still attached to the most recent commit for that pull request, so the link will continue to work:

   

Limitations

There is a limit on the number of revision URLs that can be created. If you expect your repo will have more than 1000 pull requests, consider a process to clean up tags as shown in cloudbuild-cleanup.yaml.

Understanding the code

cloudbuild.yaml

This code is based on the sample cloudbuild.yaml provided by Cloud Build, but with a noted update: the fourth step that runs update-traffic.

steps:
  - id: "build image"
    name: "gcr.io/cloud-builders/docker"
    args: ["build", "-t", "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}", "."]

  - id: "push image"
    name: "gcr.io/cloud-builders/docker"
    args: ["push", "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}"]

  - id: "deploy prod service"
    name: "gcr.io/google.com/cloudsdktool/cloud-sdk"
    entrypoint: "gcloud"
    args:
      [
        "run",
        "deploy",
        "${_SERVICE_NAME}",
        "--platform",
        "managed",
        "--region",
        "${_REGION}",
        "--allow-unauthenticated",
        "--image",
        "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}",
      ]

  # Force the new revision to serve 100% of traffic.
  - id: "ensure prod service live"
    name: "gcr.io/google.com/cloudsdktool/cloud-sdk"
    entrypoint: "gcloud"
    args:
      [
        "run",
        "services",
        "update-traffic",
        "${_SERVICE_NAME}",
        "--to-latest",
        "--platform",
        "managed",
        "--region",
        "${_REGION}",
      ]

substitutions:
  _SERVICE_NAME: myservice
  _REGION: us-central1

The configurations in cloudbuild.yaml make changes to the traffic splitting. The --to-latest parameter offers the same functionality as the Serve this revision immediately checkbox in the Cloud Run page. It ensures that this revision of the service serves 100% of traffic immediately.

cloudbuild-preview.yaml

steps:
  - id: "build image"
    name: "gcr.io/cloud-builders/docker"
    args:
      [
        "build",
        "-t",
        "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}:${_PR_NUMBER}-${SHORT_SHA}",
        ".",
      ]

  - id: "push image"
    name: "gcr.io/cloud-builders/docker"
    args:
      [
        "push",
        "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}:${_PR_NUMBER}-${SHORT_SHA}",
      ]

  - id: "deploy revision with tag"
    name: "gcr.io/google.com/cloudsdktool/cloud-sdk"
    entrypoint: "gcloud"
    args:
      [
        "run",
        "deploy",
        "${_SERVICE_NAME}",
        "--platform",
        "managed",
        "--region",
        "${_REGION}",
        "--image",
        "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}:${_PR_NUMBER}-${SHORT_SHA}",
        "--tag",
        "pr-${_PR_NUMBER}",
        "--no-traffic",
      ]

  - id: "link revision on pull request"
    name: "gcr.io/${PROJECT_ID}/deployment-previews" # our custom builder
    secretEnv: ["GITHUB_TOKEN"]
    args:
      [
        "set",
        "--project-id",
        "${PROJECT_ID}",
        "--region",
        "${_REGION}",
        "--service",
        "${_SERVICE_NAME}",
        "--pull-request",
        "${_PR_NUMBER}",
        "--repo-name",
        "${_GITHUB_REPO}",
        "--commit-sha",
        "${SHORT_SHA}",
      ]

substitutions:
  _SERVICE_NAME: myservice
  _REGION: us-central1
  _GITHUB_REPO: $(pull_request.pull_request.head.repo.full_name)

options:
  dynamicSubstitutions: true

availableSecrets:
  secretManager:
    - versionName: projects/$PROJECT_ID/secrets/github_token/versions/latest
      env: "GITHUB_TOKEN"

This code is similar to cloudbuild.yaml, but with additional steps:

1. After building and pushing the service image, cloudbuild-preview.yaml deploys the service using the --no-traffic flag. This means that even though this is the latest revision, it is not being used to serve traffic.

2. cloudbuild-preview.yaml adds a custom tag based on the pull request number. In this case, a string prefixed with "pr-" and ending in the number of the pull request.

   At this point, the revision URL is working, but the person who submitted the pull request is not able to determine this because Cloud Build logs are not visible from GitHub itself: only a link to the logs are visible. Only authenticated users of the Cloud Build project with sufficient permissions can see the logs.

3. cloudbuild-preview.yaml runs the check_status.py script, using built-in substitutions parameters provided by Cloud Build. A number of these parameters are available when working with GitHub repos, such as the pull request number, repo name, and commit SHA.

To re-run this trigger, submit another commit in GitHub. This trigger cannot be re-run from the Cloud Build page in the console.

cloudbuild-cleanup.yaml

steps:
  - id: "build image"
    name: "gcr.io/cloud-builders/docker"
    args: ["build", "-t", "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}", "."]

  - id: "push image"
    name: "gcr.io/cloud-builders/docker"
    args: ["push", "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}"]

  - id: "deploy prod service"
    name: "gcr.io/google.com/cloudsdktool/cloud-sdk"
    entrypoint: "gcloud"
    args:
      [
        "run",
        "deploy",
        "${_SERVICE_NAME}",
        "--platform",
        "managed",
        "--region",
        "${_REGION}",
        "--allow-unauthenticated",
        "--image",
        "gcr.io/${PROJECT_ID}/${_SERVICE_NAME}",
      ]

  # Force the new revision to serve 100% of traffic.
  - id: "ensure prod service live"
    name: "gcr.io/google.com/cloudsdktool/cloud-sdk"
    entrypoint: "gcloud"
    args:
      [
        "run",
        "services",
        "update-traffic",
        "${_SERVICE_NAME}",
        "--to-latest",
        "--platform",
        "managed",
        "--region",
        "${_REGION}",
      ]

  # Cleanup tags against closed pull requests
  - id: "clean up old tag"
    name: "gcr.io/${PROJECT_ID}/deployment-previews" # our custom builder
    secretEnv: ["GITHUB_TOKEN"]
    args:
      [
        "cleanup",
        "--project-id",
        "${PROJECT_ID}",
        "--region",
        "${_REGION}",
        "--service",
        "${_SERVICE_NAME}",
        "--repo-name",
        "${_GITHUB_OWNER}/${REPO_NAME}",
      ]

substitutions:
  _SERVICE_NAME: myservice
  _REGION: us-central1
  _GITHUB_OWNER: $(push.repository.owner.name)

options:
  dynamicSubstitutions: true

availableSecrets:
  secretManager:
    - versionName: projects/$PROJECT_ID/secrets/github_token/versions/latest
      env: "GITHUB_TOKEN"

This code is an alternative to cloudbuild.yaml, with added cleanup functionality. The initial steps perform the deployment, and the functionality is then extended as follows:

1. Using the Discovery API and GitHub APIs, determine which tags for the service are for closed pull requests. At a minimum, there will be the pull request that was merged, causing this trigger to fire.

2. Delete the tags identified.

check_status.py

def set(
    dry_run: str,
    project_id: str,
    region: str,
    service: str,
    repo_name: str,
    commit_sha: str,
    pull_request: str,
) -> None:
    """Set a status on a GitHub commit to a specific revision URL"""
    service_obj = get_service(project_id, region, service)
    revision_url = get_revision_url(service_obj, tag=make_tag(pull_request))

    ghtoken = os.environ.get("GITHUB_TOKEN", None)

    if not ghtoken:
        raise ValueError("GITHUB_TOKEN not defined.")

    try:
        repo = github.Github(ghtoken).get_repo(repo_name)
    except GithubException as e:
        error(
            e.data["message"],
            context=f"finding repo {repo_name}. Is it a private repo, and does your token have the correct permissions?",
        )

    try:
        commit = repo.get_commit(sha=commit_sha)
    except GithubException as e:
        error(e.data["message"], context=f"finding commit {commit_sha}")

    # ...

    commit.create_status(
        state="success",
        target_url=revision_url,
        context="Deployment Preview",
        description="Your preview is now available.",
    )
    click.secho("Success: ", fg="green", bold=True, nl=False)
    click.echo(
        f"Status created on {repo_name}, commit {commit.sha[:7]}, "
        f"linking to {revision_url} on service {service_obj['metadata']['name']}"
    )

The check_status.py script takes the provided information about the Cloud Run service, about the GitHub repo and commit, and then performs the following operations:

• Retrieve the service name, tag, and revision URL using the Google API Python client.
• Retrieve the GitHub token from the environment variable, provided by Secret Manager.
• Create a status on the given commit, linking to the retrieved revision URL, using a GitHub Client API for Python.