Integrating Google Cloud Deploy with your CI system

This document describes how to invoke your Google Cloud Deploy delivery pipeline from your continuous integration (CI) system.

Integrating Google Cloud Deploy with your CI system is as simple as adding a call to the Google Cloud Deploy gcloud CLI. This call occurs at the point in your CI pipeline at which your application is ready to be deployed.

Before you begin

The instructions on this page assume you already meet the following conditions:

Calling Google Cloud Deploy from your CI pipeline

The following command creates a new release, thus invoking a delivery pipeline instance:

gcloud deploy releases create RELEASE_NAME \
  --delivery-pipeline=PIPELINE_NAME \
  --region=REGION
  --annotations=[KEY=VALUE,...]
  --images=[IMAGE_LIST]

Where...

  • RELEASE_NAME

    is a name you give to this release. This value is required.

  • PIPELINE_NAME

    is the name of your registered delivery pipeline. This value is required.

  • REGION

    is the region in which you're creating this release. The region doesn't need to be the same region in which you're ultimately deploying your application.

  • [KEY=VALUE,...]

    is an optional list of one or more annotations to apply to the release, in the form of key-value pairs.

    You can use annotations to track release provenance, for example, by passing an annotation like commitId=0065ca0. All annotations on the release are returned when you list or get the release, and are displayed with the release in the Google Cloud Console, so you can see release provenance there too.

  • [IMAGE_LIST]

    is a comma-separated list of image-name-to-image-path replacements. For example: --images=image1=path/to/image1:v1@sha256:45db24,image2=path/to/image2:v1@sha256:55xy18.

    This value isn't required if you pass --build-artifacts, which identifies a Skaffold build artifacts output file.

    When Google Cloud Deploy renders the manifest, the image name in the unrendered manifest is replaced with the full image reference in the rendered manifest. That is, image1, from this example, is in the unrendered manifest and is replaced in the rendered manifest with path/to/image1:v1@sha256:45db24.

Example using direct image reference

The following command creates a new release, passing an image reference directly, rather than a build artifacts file:

gcloud deploy releases create my-release \
  --delivery-pipeline=web-app \
  --region=us-central1
  --images=image1=path/to/image1:v1@sha256:45db24

Build artifacts versus images

On the gcloud deploy releases create command, you can pass either a set of image references or a build artifacts file reference.

  • Use --images=[NAME=TAG,...] to refer to one or more individual container images.

    This value is a reference to a collection of individual image name to image full path replacements. Here's an example:

    gcloud deploy releases create my-release --images=image1=path/to/image1:v1@sha256:45db24

  • Use --build-artifacts= to point to a Skaffold build artifacts output file.

Cloud Build examples, passing a build artifacts file

Docker build example

The following YAML file demonstrates Cloud Build for a Docker build image push, and ulimately creates a Google Cloud Deploy release.

This example builds and pushes an image to an artifact repository and constructs a command to create a release, with a release name based on the short commit SHA. This example must be used as a Cloud Build SCM trigger because it relies on the $COMMIT_SHA variable.

This example pushes an image to a Docker label that's the same as the commit hash of the source repo. Then the same commit hash, as a Docker label, is referenced from the release-command arguments.

# Build and tag using commit sha
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '.', '-t', 'REPO_LOCATION/$PROJECT_ID/IMAGE_NAME:${COMMIT_SHA}', '-f', 'Dockerfile']
# Push the container image
- name: 'gcr.io/cloud-builders/docker'
  args: ['push', 'REPO_LOCATION/$PROJECT_ID/IMAGE_NAME:${COMMIT_SHA}']
# Create release in Google Cloud Deploy
- name: gcr.io/google.com/cloudsdktool/cloud-sdk
  entrypoint: gcloud
  args:
    [
      "deploy", "releases", "create", "rel-${SHORT_SHA}",
      "--delivery-pipeline", "PIPELINE_NAME",
      "--region", "us-central1",
      "--annotations", "commitId=${REVISION_ID}",
      "--images", "IMAGE_NAME=REPO_LOCATION/$PROJECT_ID/IMAGE_NAME:${COMMIT_SHA}"
    ]

Note that the image name at the end of this example, "--images", "IMAGE_NAME= is substituted in the rendered manifest with the full image reference.

An example Cloud Build configuration using Skaffold

The following YAML file is the content of a Cloud Build build configuration that includes a call to Google Cloud Deploy to create a release, with a release name based on the date. This example also shows Skaffold used for the build.

- name: gcr.io/k8s-skaffold/skaffold
  args:
    - skaffold
    - build
    - '--interactive=false'
    - '--file-output=/workspace/artifacts.json'
- name: gcr.io/google.com/cloudsdktool/cloud-sdk
  entrypoint: gcloud
  args:
    [
      "deploy", "releases", "create", "rel-${SHORT_SHA}",
      "--delivery-pipeline", "PIPELINE_NAME",
      "--region", "us-central1",
      "--annotations", "commitId=${REVISION_ID}",
      "--build-artifacts", "/workspace/artifacts.json"
    ]

Using annotations to track the release's provenance

The --annotations= flag lets you apply one or more arbitrary key-value pairs to the release that this command creates. You would add this flag to the gcloud deploy releases create command.

For example, you can use the following key-value pairs to track the source of the image to be deployed.

Here's an example:

gcloud deploy releases create web-app-1029rel \
  --delivery-pipeline=web-app \
  --region=us-central1
  --annotations=commitId=0065ca0,author=user@company.com
  --images=image1=path/to/image1:v1@sha256:45db24

You could also create an annotation whose value is the URL pointing to the pull request, for example. For more information, see Using labels and annotations with Google Cloud Deploy.