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.

    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 substitution for the repository location, repository name, and image. You specify the values for these variables at build time.
    • $PROJECT_ID is a default substitution that Cloud Build resolves with the Google Cloud project ID for the build.

      • 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

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

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

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.

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

To configure your build:

  1. In the directory with your Cloud Build build config file, create a file named requirements.txt with the following dependencies:

    twine
    keyrings.google-artifactregistry-auth
    
  2. To upload a Python package to your Python repository in your build, 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 that Cloud Build resolves with the Google Cloud project ID for the build.

      • 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 appropriate steps to your build config file.

    • If both services are in the same project, you only need to run the pip install command.

      steps:
      - name: python
        entrypoint: pip
        args:
        - 'install'
        - '--index-url'
        - 'https://${_LOCATION}-python.pkg.dev/$PROJECT_ID/${_REPOSITORY}/simple/'
        - '${_PACKAGE}'
        - '--verbose'
      
    • If Cloud Build and Artifact Registry are in different projects, you must install the dependencies in requirements.txt before installing packages.

      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" .