Building and Storing Containers with Cloud Build

Pipeline integration and optimization is the practice of moving container images securely from Cloud Build (opens in a new tab) to Artifact Registry (opens in a new tab) while keeping builds fast and trustworthy. Cloud Build builds the image from source, checks the image for vulnerabilities, and then stores the image in Artifact Registry for deployment. Efficient layer design reduces rebuild time and storage use, while scanning and deployment policy protect the software supply chain.

1.1Secure Transfer from Cloud Build to Artifact Registry

Secure transfer from Cloud Build to Artifact Registry means the built image is pushed to a versioned Docker repository address in the form LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. The simplest transfer runs gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME from the directory with source code and a Dockerfile, which builds the image and pushes it to Artifact Registry. A build config file gives more control by defining steps that run builders such as gcr.io/cloud-builders/docker, and each build step container attaches to a local Docker network named cloudbuild that hosts Application Default Credentials for Google Cloud services.

Cloud Build can store a built image in three different ways:

• Use the images field to store a Docker image in Artifact Registry after the build completes, which makes the stored image appear in the build results.
• Use the artifacts.oci field with file and registryPath to upload an Open Container Initiative (OCI) image, including multi-architecture images, to a supported Artifact Registry repository.
• Use the docker push command inside a build step to store a container image as part of the build flow, which does not display the image in the build results.

Choose the images field when visibility in build results matters, because results include the Build description page in the console, Build.get(), and gcloud builds list. Choose docker push inside the step sequence when the push must happen at a specific point in the pipeline, such as only after a vulnerability check passes.

1.2Automated Vulnerability Scanning in the Pipeline

Automated vulnerability scanning in the pipeline uses Artifact Analysis (opens in a new tab) to find package vulnerabilities before an image reaches Artifact Registry or production. Automatic vulnerability scanning scans container images when they are uploaded to Artifact Registry and continuously monitors the data for new vulnerabilities for up to 30 days after the push. The On-Demand Scanning API scans local images or images stored in Artifact Registry on request, so Cloud Build can scan an image after it is built and block the upload to Artifact Registry if vulnerabilities at a specified severity are found.

A secure Cloud Build pipeline orders build, scan, check, and push so only clean images are stored:

1. Build: Build the image with Docker and record its tag and digest to /workspace/image-digest.txt.
2. Scan: Call the On-Demand Scanning API to scan the built image and save the returned scan ID to /workspace/scan_id.txt.
3. Severity check: List vulnerabilities for the scan ID, check vulnerability.effectiveSeverity, and fail the build with exit 1 if a blocked severity is found.
4. Push: Push the image to Artifact Registry with docker push only if the severity check succeeded, and list the image in the images field for visibility.

The severity gate blocks only the levels explicitly defined in the _SEVERITY substitution. Supported levels are:

• CRITICAL
• HIGH
• MEDIUM
• LOW

Because the check uses exact matching, specifying only HIGH will not block CRITICAL, so teams that want to block High and above use a regular expression such as CRITICAL|HIGH.

1.3Enforcing Integrity at Deploy Time

Enforcing integrity at deploy time means only images that meet security proof are allowed into supported Google Cloud environments. Binary Authorization (opens in a new tab) enforces a deployment policy when a deploy is attempted, for example by allowing deployment only if an image is signed for compliance with a vulnerability scan policy. This enforcement depends on earlier pipeline evidence, including On-Demand Scanning results, automatic scan data, and build provenance from Cloud Build.

Cloud Build can generate build provenance that provides Supply Chain Levels for Software Artifacts (SLSA) Level 3 assurance, which verifies the build source, entry point, parameters, and builder identity. Cloud Build also runs each build in a fresh virtual machine environment that is destroyed after the build, so no residual files or settings carry over to interfere with the next build or hide tampering. Together, ephemeral builds, signed provenance, and Binary Authorization let operators allow only code built from verified sources by a trusted build system.

1.4Efficient Layer Caching and Image Hygiene

Efficient layer caching in Artifact Registry relies on how container image layers are constructed and reused. A container image is built incrementally from layers, where each instruction in a Dockerfile corresponds to a layer in the Docker image. Images in the same registry that share common layers reuse those layers for storage efficiency, while layers are not shared across different registries. When an image is deleted, its unreferenced layers are cleaned up daily rather than immediately.

Dockerfiles stay fast when stable dependency steps are ordered before frequently changing code. Node.js Dockerfiles copy package*.json first and run npm install --omit=dev before copying application code, so code changes do not force dependency reinstalls. Python Dockerfiles copy requirements.txt and run pip install -r requirements.txt before copying code for the same reason, and Java and .NET examples use multi-stage builds where a builder stage compiles the artifact and only the final jar or published output is copied into a smaller runtime image. Removing unused container images further reduces storage costs and lowers the risk of running old, vulnerable software.

Build configuration and automation in Cloud Build (opens in a new tab) is the practice of defining container construction as code in a cloudbuild.yaml or cloudbuild.json file so source code flows automatically to a versioned image in Artifact Registry. The config file declares an ordered list of build steps, substitution variables for different environments, and output fields that control where the finished image is stored. When combined with manual submission or build triggers, the same file produces repeatable builds across development, staging, and production.

2.1Multi-Step Build Processes with cloudbuild.yaml

A cloudbuild.yaml file defines automation through its steps field, where each build step runs a container as an instance of docker run. Each step names a builder image in name, such as gcr.io/cloud-builders/docker, and passes tool commands in args, such as build or push. By default Cloud Build runs all steps serially on the same machine, and a config can include up to 300 steps with up to 100 arguments per step.

A typical containerization pipeline moves source code through an ordered sequence:

1. Build: A docker builder step runs docker build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME . to build the image from the Dockerfile and source in the workspace.
2. Push: A second docker builder step runs docker push with the same Artifact Registry path to send the image from the build worker to the repository.
3. Deploy or verify: A later step uses another builder, such as gcr.io/google.com/cloudsdktool/cloud-sdk with a gcloud entrypoint, to scan the image, check vulnerabilities, or create a Compute Engine instance from the pushed image.

Steps can share data through the /workspace directory, so one step can write an image digest or scan ID to a file that a later step reads. Use id to name steps for tracking, waitFor to allow steps to run concurrently, and -f DOCKERFILE_PATH in args when the Dockerfile lives in a different directory than the source.

2.2Substitution Variables for Diverse Environments

Substitution variables in Cloud Build are named placeholders that let one cloudbuild.yaml file build different projects, repositories, and environments without editing the file. Custom substitutions start with an underscore, such as $_IMAGE, $_PROJECT_ID, $_SERVICE_ACCOUNT, and $_SEVERITY, and are declared in a top-level substitutions map with default values. Built-in values such as ${PROJECT_ID} and ${BUILD_ID} resolve automatically at build time, so the image path LOCATION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/IMAGE_NAME adapts to the project that runs the build.

The build depends on options flags to control how substitutions flow into containers. Setting dynamicSubstitutions: true allows values like ${BUILD_ID} to resolve correctly, while automapSubstitutions: true maps substitution variables into the container environment. Setting substitutionOption: ALLOW_LOOSE tells Cloud Build to ignore unused substitutions or dynamic script arguments instead of failing. A trigger or gcloud builds submit command can then override any custom value at run time to target a new region, repository, or severity threshold.

2.3Automating Delivery with Submit Commands and Build Triggers

Automation in Cloud Build starts a container build from source without manually running Docker locally, either on demand or automatically when source changes. The command gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY sends the source directory and config file to Cloud Build, which runs each step and stores the result. If no paths are given, Cloud Build assumes the config file and source are in the current working directory.

The same delivery goal can be started in three ways:

• Use a build config file with gcloud builds submit --config to run explicit multi-step logic such as build, scan, severity check, and push.
• Use only a Dockerfile with gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME to build an image without writing a config file.
• Use buildpacks (opens in a new tab) with gcloud builds submit --pack image=LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME to build an image with no Dockerfile and no config file, optionally adding builder= and env= values.

Build triggers extend this automation by watching a repository and starting the same config, Dockerfile, or buildpacks build automatically on pushes or pull requests. A trigger that uses buildpacks can therefore rebuild and republish an image on every source change, streamlining delivery across diverse environments from one definition.

2.4Storing Built Images in Artifact Registry from the Build

Storing images in Artifact Registry connects the end of the build to a secure Docker repository addressed as LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. Cloud Build supports three output mechanisms that differ in what they store and whether the result appears in build metadata.

The images field lists one or more image paths to push after all steps succeed, and the build fails if a listed image was not produced. The docker push step runs inside the step sequence, so it can occur before later validation or deployment steps. To store the image during the flow and still display it in build results, include both the docker push step and the images field with the same image path.

Artifact Management and Repository Security is the practice of storing Docker container images in centrally managed, versioned repositories with controlled access and secure publishing. In Google Cloud, Artifact Registry (opens in a new tab) provides that central location for packages and Docker images, while Cloud Build (opens in a new tab) builds images from source and pushes them to Artifact Registry. Identity and Access Management (IAM) controls who can administer repositories and who can push or pull images.

3.1Docker Repositories for Container Images

A Docker repository in Artifact Registry is a regional or multi-regional container for storing multiple related container images in one Google Cloud project. Each repository has its own location, such as us-west1, and images are addressed as LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG, where docker.pkg.dev is the hostname for Docker-format repositories. You can create multiple separately controlled repositories in the same project to group images by team or stage, such as testing, staging, or production, and control access at the repository level.

Images inside a Docker repository are versioned by tag and manifest digest, and tags can be mutable or immutable. Container images are built from layers, where each Dockerfile instruction creates a layer, and images in the same registry that share layers reuse that storage for efficiency. Layers are never shared across different registries for security, and layers that are no longer referenced by any image are deleted daily. For all push and pull requests to the pkg.dev domain, the target repository must already exist before the push.

3.2Granular Access Control With IAM

Granular access control in Artifact Registry means granting IAM roles on individual repositories instead of on a whole registry host. IAM provides consistent credentials for Cloud Build, Google Kubernetes Engine (GKE), Cloud Run, Compute Engine, and developer tools, and permissions are managed directly on the repository with no Cloud Storage buckets to manage. For example, access to images in us-docker.pkg.dev/my-project/team1 can be controlled separately from us-docker.pkg.dev/my-project/team2, and conditional access can be granted with IAM and repository tags.

The build and runtime service accounts receive scoped repository permissions:

• The default Cloud Build service account can upload and download artifacts and create gcr.io repositories in the same Google Cloud project.
• The Compute Engine default service account, which is also the default GKE node service account and Cloud Run default service account, can pull from repositories in the same project.
• If Cloud Build and the repository are in different projects, or if a build uses a user-specified service account, the build service account must be granted the Artifact Registry Writer role in the project that holds the repositories.

Repositories can be further protected by encrypting each repository with customer-managed encryption keys (CMEK) and by placing repositories inside a VPC Service Controls security perimeter. Artifact Registry also supports vulnerability scanning and metadata management through Artifact Analysis, Pub/Sub notifications for repository changes, and image prewarming with Image streaming to reduce GKE cold-start latency.

3.3Secure Publishing From Cloud Build to Artifact Registry

Secure publishing from Cloud Build to Artifact Registry is an automated flow where source code moves through ordered build steps and the resulting image is pushed to a specific repository. Cloud Build executes each build step in a Docker container attached to a local cloudbuild network, using supported builders, community builders, or custom builders such as gcr.io/cloud-builders/docker. A Docker build tags the image with the full Artifact Registry path and lists that path in the images field so Cloud Build pushes it after the build succeeds.

The general lifecycle of a Cloud Build build is:

1. Prepare code: Prepare application code and needed assets for the build.
2. Create build config: Create a YAML or JSON build config file that defines fetch, test, and build tasks.
3. Submit build: Submit the build manually with gcloud builds submit or automatically with a build trigger connected to Cloud Source Repositories, GitHub, or Bitbucket.
4. Execute steps: Cloud Build executes each build step in order in its isolated worker environment.
5. Push artifacts: Built artifacts are pushed to Artifact Registry, and runtimes such as GKE, Cloud Run, Compute Engine, and App Engine flexible environment can then deploy those artifacts.

A Docker build config reuses the same file across environments by using substitutions for location, repository, image, and project. User-defined substitutions such as ${_LOCATION}, ${_REPOSITORY}, and ${_IMAGE} are supplied at build time, while the default substitution $PROJECT_ID resolves to the project where Cloud Build runs. The same config can therefore push us-east1-docker.pkg.dev/PROJECT_ID/my-repo/my-image for one run and a different location, repository, or image for the next without editing the file.

3.4Container Registry Compared With Artifact Registry

Artifact Registry expands on Container Registry and is the recommended container registry for Google Cloud. The security and management differences center on how repositories are created, isolated, and authorized.

Because administration is separated from usage, repository owners create and secure the repository first, then developers and build service accounts only receive the push or pull access they need for that repository.

Key Facts

• Cloud Build pushes container images to Artifact Registry at addresses in the form LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME.
• An image stored with the images field appears in Cloud Build results, while an image stored with docker push inside a build step does not.
• The On-Demand Scanning API lets Cloud Build scan an image and block the push to Artifact Registry, while automatic vulnerability scanning monitors images already stored in Artifact Registry for up to 30 days.
• Binary Authorization enforces deployment policy by allowing deployment only for images with required proof such as vulnerability scan compliance and SLSA Level 3 build provenance.
• Artifact Registry grants access with IAM roles on individual repositories, and pushes across projects require the Artifact Registry Writer role on the repository project.