Integrating with Cloud Build

This page describes how to configure Cloud Build to store built artifacts in an Artifact Registry repository.

Before you begin

  1. If the target repository does not exist, create a new repository.
  2. If Cloud Build and your repository are in different projects or if you are using a user-specified service account to run builds, grant the Artifact Registry Writer role to the build service account in the project with the repositories.

    The default Cloud Build service account has permissions to upload and download from repositories in the same project.

Configuring a Docker build

After you have granted permissions to the target repository, you are ready to configure your build.

To configure your build:

  1. In your build config file, add the step to build and tag the image.

    The following example uses the following values for an image that is in the same directory as the build config file:

    • The repository location us-central1
    • The project ID of the build, resolved with the default substitution $PROJECT_ID
    • The repository name my-repo
    steps:
    - name: 'gcr.io/cloud-builders/docker'
      args: [ 'build', '-t', 'us-central1-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/${_IMAGE}', '.' ]
    images:
    - '${_LOCATION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/${_IMAGE}'
    

    This snippet uses Cloud Build substitutions. This approach is useful if you want to use the same build config file to push images to repositories for different environments, such as testing, staging, or production.

    • ${_LOCATION}, ${_REPOSITORY}, and ${_IMAGE} are user-defined substitutions for the repository location, repository name, and image. You specify the values for these variables at build time.
    • $PROJECT_ID is a default substitution for the Google Cloud project ID.

      • If you run the gcloud builds submit command, Cloud Build uses the active project ID in the gcloud session.
      • If you use a build trigger, Cloud Build uses the ID of the project where Cloud Build is running.

      Alternatively, you can use a user-defined substitution instead of $PROJECT_ID so that you can specify a project ID at build time.

  2. When you are ready to run the build, specify values for the user-defined substitutions. For example, this command substitutes:

    • us-east1 for the repository location
    • my-repo for the repository name
    • my-image for the image name
    gcloud builds submit --config=cloudbuild.yaml \
      --substitutions=_LOCATION="us-east1",_REPOSITORY="my-repo",_IMAGE="my-image" .
    

Configuring a Java build

Java package repositories are in Preview.

After you have granted permissions to the target repository, you are ready to configure your build. The following instructions describe configuring your build to upload a Java package to a Maven repository.

To configure your build:

  1. Set up authentication for Maven. Ensure that you specify the correct target project and repository in your pom.xml file.

  2. In your Cloud Build build config file, add the step to upload the package with Maven:

    steps:
    - name: gcr.io/cloud-builders/mvn
      args: ['deploy']
    

Configuring a Node.js build

Node.js repositories are in Preview.

After you have granted permissions to the target repository, you are ready to configure your build. The following instructions describe configuring your build to upload a Node.js package to an npm repository.

To configure your build:

  1. Set up authentication for npm. Ensure that you specify the correct target project and repository in your .npmrc file.

  2. Add a script to the package.json file in your project that refreshes the access token for authentication with the repository.

    "scripts": {
     "artifactregistry-login": "npx google-artifactregistry-auth"
    }
    
  3. In your build config file, add the step to upload the package to the repository.

    steps:
    - name: gcr.io/cloud-builders/npm
      args: ['run', 'artifactregistry-login', '${_NPMRC}']
    - name: gcr.io/cloud-builders/npm
      args: ['publish', '${_PACKAGE}']
    

    In this snippet:

    • ${_PACKAGE} is the location of the package, the folder or a gzipped tarball that contains package.json and other files in your package.
    • ${_NPMRC} is the path to the .npmrc file.

    Specify the values for these variables with Cloud Build substitutions at build time.

    For example, this command uploads a package in a directory named src with configuration in /home/username/.npmrc:

    gcloud builds submit --config=cloudbuild.yaml \
        --substitutions=_PACKAGE="src",_NPMRC="/home/username/.npmrc" .
    

Configuring a Python build

Python repositories are in Preview.

After you have granted permissions to the target repository, you are ready to configure your build. The following instructions describe configuring your build to upload a Python package to a Python repository and install the package using pip.

If you want to build and containerize a Python application and then push it to a Docker repository, see the Building Python applications in the Cloud Build documentation.

To configure your build:

  1. In your Python project, create a file named requirements.txt in the same location as your Cloud Build build config file. Include the following lines:

    twine
    keyrings.google-artifactregistry-auth
    

    Twine is a tool for uploading packages to a repository. keyrings.google-artifactregistry-auth is the keyring backend to that handles authentication with Artifact Registry.

  2. To upload your built Python package to your Python repository, add the following steps to your build config file:

    steps:
    - name: python
      entrypoint: pip
      args: ["install", "-r", "requirements.txt", "--user"]
    - name: python
      entrypoint: python
      args:
      - '-m'
      - 'twine'
      - 'upload'
      - '--repository-url'
      - 'https://${_LOCATION}-python.pkg.dev/$PROJECT_ID/${_REPOSITORY}/'
      - 'dist/*'
    

    In this snippet, the first step installs Twine and the Artifact Registry keyring backend. The second step uploads your built Python files in the dist subdirectory. Adjust the paths to requirements.txt and your built Python files if they don't match the snippet.

    The repository path includes Cloud Build substitutions. This approach is useful if you want to use the same build config file to upload packages to repositories for different environments, such as testing, staging, or production.

    • ${_LOCATION} and ${_REPOSITORY} are user-defined substitutions for the repository location, repository name, and package name. You specify the values for these variables at build time.
    • ${_PROJECT_ID} is a default substitution for the Google Cloud project ID.

      • If you run the gcloud builds submit command, Cloud Build uses the active project ID in the gcloud session.
      • If you use a build trigger, Cloud Build uses the ID of the project where Cloud Build is running.

      Alternatively, you can use a user-defined substitution instead of $PROJECT_ID so that you can specify a project ID at build time.

  3. To install the package from the Python repository, add the following steps to your build config file:

    steps:
    - name: python
      entrypoint: pip
      args: ["install", "-r", "requirements.txt", "--user"]
    - name: python
      entrypoint: pip
      args:
      - 'install'
      - '--index-url'
      - 'https://${_LOCATION}-python.pkg.dev/$PROJECT_ID/${_REPOSITORY}/simple/'
      - '${_PACKAGE}'
      - '--verbose'
    

    This snippet includes an additional ${_PACKAGE} substitution for the package name.

  4. When you are ready to run the build, specify values for the user-defined substitutions. For example, this command substitutes:

    • us-east1 for the repository location
    • my-repo for the repository name
    • my-package for the package name
    gcloud builds submit --config=cloudbuild.yaml \
      --substitutions=_LOCATION="us-east1",_REPOSITORY="my-repo",_PACKAGE="my-package" .