Artifact Registry Repositories, Promotion and Scanning

Lifecycle policies and promotion workflows in Artifact Registry (opens in a new tab) control what stays in a repository and what moves forward toward production. Cleanup policies automatically delete stale artifact versions to lower storage cost and reduce attack surface, while promotion workflows copy or re-tag only validated artifacts from development to testing to production repositories. Security checks and access controls become stricter at each stage boundary.

1.1Automated Cleanup Policies in Artifact Registry

Automated cleanup policies in Artifact Registry are repository-level rules that delete or preserve artifact versions based on age, tag state, and version count. Removing unused images prevents redeployment of old, vulnerable software, including unversioned, untagged, or stale release-candidate images after a retention period. Policies can run in dry-run mode, which only logs deletion candidates, or in enforced mode, which actually deletes or keeps artifacts.

The three policy types differ by action and selection criteria:

When package_name_prefixes is set on a keep-most-recent-versions policy, only artifacts matching those prefixes count toward keep_count, so other packages in the same repository are not protected. In Terraform, behavior is controlled by cleanup_policy_dry_run on the google_artifact_registry_repository resource, where true logs candidates without deletion and false enforces deletion, with one cleanup_policies block per rule containing an id, an action of DELETE or KEEP, and either a condition or a most_recent_versions block.

1.2Secure Promotion Workflows Across Registries

A secure promotion workflow in Artifact Registry is a staged pipeline that moves a validated artifact from a development repository to a testing repository and then to a production repository. Repository-level access control separates the stages so development writers cannot write directly to production, for example by granting different identities access to us-docker.pkg.dev/my-project/dev versus us-docker.pkg.dev/my-project/prod. Administrators own the stage boundaries by creating repositories, while developers and build service accounts only push and pull within their allowed stage.

A robust promotion sequence flows in order:

1. Build and pre-push scan: Cloud Build builds the image and calls On-Demand Scanning on the local image, then blocks upload to Artifact Registry if vulnerabilities exceed the severity threshold.
2. Push to development: The build pushes the image to the development repository, which triggers automatic scanning by Artifact Analysis (opens in a new tab) on every push with continuous updates as new vulnerabilities are discovered.
3. Attach validation metadata: People or automation attach structured metadata to the image, such as an occurrence recording that the image passed integration tests or a vulnerability scan.
4. Promote with attestation: The pipeline copies or re-tags the image digest into testing and then production repositories only after creating the required attestation, with more attestations required closer to production.
5. Enforce at deploy: Binary Authorization enforces its policy when deployment is attempted, allowing only images from trusted registries that carry the required attestations.

Security Command Center aggregates scan findings across projects and running workloads and can export them to BigQuery for analysis, so central visibility follows the artifact without replacing stage-gate enforcement.

1.3Integrity Controls for Promoted Artifacts

Integrity controls for promoted artifacts ensure that the exact bits validated in testing are the bits deployed in production. Binary Authorization verifies container integrity at deploy time based on attestations and applies policies at the cluster level, so development, testing, and production clusters can require different attestation sets for the same image digest. Continuous Validation monitors active Pods on Google Kubernetes Engine (GKE) against the platform policy and emits Logging alerts if running containers become non-compliant after admission.

Promotion pipelines depend on three complementary protections:

• Immutable references: Enable immutable image tags so a tag always points to the same digest, or reference images strictly by SHA-256 digest such as @sha256:... to prevent tag-mutation attacks between stages.
• Attested gates: Generate attestations automatically in Cloud Build or GitHub Actions and integrate Artifact Analysis metadata, including vulnerability results and Software Bill of Materials (SBOM), with Binary Authorization attestations to block images that fail thresholds.
• Supply-chain isolation: Configure virtual repositories with upstream priorities that favor internal repositories over public registries to resist dependency confusion, and use remote repositories backed by verified sources for external dependencies.

For emergency incidents, breakglass deployments bypass Binary Authorization admission, but the bypass emits audit log events that should trigger Monitoring alerts to the security operations team.

Google Cloud Artifact Registry (opens in a new tab) stores each package format in its own repository, so a multi-format supply chain uses a hierarchy of repositories per format rather than one mixed repository. The hierarchy combines standard repositories that hold private artifacts, remote repositories that cache public upstreams, and virtual repositories that present one endpoint with an ordered upstream policy. Together these modes let Cloud Build, Google Kubernetes Engine (GKE), Cloud Run, and other consumers resolve private and public dependencies through a single address while controlling caching, cost, and placement by region or multi-region.

2.1Standard, Remote, and Virtual Repository Roles

The three repository modes divide storage, caching, and resolution work for each format such as Docker, Maven, npm, Python, Apt, and Yum. A standard repository is the system of record for artifacts the organization builds, a remote repository is a caching proxy for an external or cross-project upstream, and a virtual repository does not store artifacts itself but routes requests to its upstreams in priority order.

A virtual repository depends on its upstreams, so the upstreams must exist in the same format before the virtual endpoint can resolve them. Because clients configure only the virtual endpoint, adding or replacing an upstream changes resolution without reconfiguring every build or cluster.

2.2Upstream Priority and Secure Dependency Resolution

A virtual repository upstream policy controls the search order across its upstream standard and remote repositories (opens in a new tab). When a build requests a package, the request flows from the build client to the virtual repository, and the virtual repository queries upstreams in configured priority order until one returns the artifact. Configuring the policy to prioritize the standard repository with private artifacts over the remote repository that caches public artifacts ensures internal names resolve internally first.

This ordering directly mitigates dependency confusion attacks, where an attacker publishes a higher-version public package with the same name as a private package. If the remote cache were checked first, the build could pull the malicious public artifact; when the private standard repository is checked first, the private artifact wins. The same control plane supports broader protections through access control, Virtual Private Cloud (VPC) Service Controls perimeters, organization policies, and Artifact Analysis scanning for vulnerabilities, SBOMs, and Vulnerability Exploitability eXchange (VEX) statements.

2.3Repository Location Across Regions and Multi-Regions

Repository location is the regional or multi-regional placement that balances latency, availability, bandwidth cost, and compliance for artifact consumers. Creating repositories in the same region as GKE, Cloud Run, Cloud Build, and other Google Cloud services that interact with the repository reduces latency and network egress cost, and there is no charge for egress from Artifact Registry to other Google Cloud services in the same region. Egress from a multi-region to a corresponding regional service is free only in limited cases, so placement still matters for multi-regional designs.

Location decisions weigh four documented factors:

• Latency between the repository and builds, clusters, and developer workstations
• Availability of artifacts to regional workloads and external consumers
• Bandwidth and egress charges for same-region, cross-region, and internet downloads
• Compliance requirements that mandate storage in specific regions

Multi-region egress has narrow exceptions. For the us multi-region, egress to a United States region such as us-central1 is not charged, while egress to any region in Canada or South America is charged. For the asia multi-region, egress to Asian regions such as asia-northeast1 is not charged, while egress to regions in Australia is charged. Consumers outside Google Cloud follow the same tradeoff: a development team in Australia downloading to local workstations sees lower latency and egress charges from an Australian region than from another continent.

Two placement controls affect performance and governance. Image streaming for GKE and Managed Service for Apache Spark works only when container images are stored in Artifact Registry repositories in the same region as the workloads or in a corresponding multi-region, and streaming lets workloads with larger images start before the entire image is downloaded. For compliance, an organization policy with a resource locations constraint allows repository creation only in compliant regions; Artifact Registry enforces the constraint only after it is included in the policy, and existing repositories in non-compliant locations require manual migration of artifacts followed by deletion of the old repository.

2.4Multi-Project Pipeline Using Maven and Docker Repositories

A multi-project pipeline using Maven and Docker repositories separates development and runtime concerns across projects while keeping one endpoint per format. In this pattern all repositories, Cloud Build jobs, and GKE clusters share the same region to preserve same-region egress and streaming benefits, with a Maven hierarchy for Java dependencies and a Docker hierarchy for container images.

The pipeline runs in order:

1. Build Java application in development project: Cloud Build requests public Java dependencies through the Maven virtual repository, which serves them from the Maven remote repository that proxies Maven Central, then Cloud Build uploads the built package to the standard Maven repository.
2. Containerize application in runtime project: Cloud Build downloads the application and any public Java dependencies through the same Maven virtual repository, which serves the private application from the development-project standard repository and public dependencies from the remote cache.
3. Publish container image in runtime project: Cloud Build uploads the built container image to the standard Docker repository in the runtime project.
4. Deploy to GKE from virtual Docker endpoint: GKE pulls images from the Docker virtual repository, which serves private images from the upstream standard Docker repository and public images from the upstream remote repository that caches Docker Hub.

Implementing security controls and vulnerability scanning in Artifact Registry (opens in a new tab) means protecting stored artifacts at rest, in transit, and on the path to runtime. Artifact Analysis (opens in a new tab) (formerly Container Analysis) provides software composition analysis, vulnerability scanning, and structured metadata storage for images in Artifact Registry. Scan findings flow from Artifact Registry to deployment gates and monitoring systems, so only compliant images reach supported runtimes such as Google Kubernetes Engine, Cloud Run, and App Engine.

3.1Repository Access Control and Network Perimeter

Repository access control in Artifact Registry enforces least privilege at the repository level rather than at a broad storage bucket. Each repository grants permissions with Artifact Registry Identity and Access Management (IAM) roles, so us-docker.pkg.dev/my-project/team1 and us-docker.pkg.dev/my-project/team2 can have different readers and writers. Conditional access combines IAM conditions with repository tags for finer-grained decisions, and audit activity is tracked with Cloud Logging. Network isolation is enforced by adding Artifact Registry to a VPC Service Controls perimeter, which places API access inside a trust boundary and blocks exfiltration to outside projects.

Public exposure requires explicit identity grants and quota guardrails. Making a repository public means granting the Artifact Registry Reader role to allUsers, while limiting to Google-authenticated users means granting it to allAuthenticatedUsers instead. Before publishing, verify that artifacts contain no credentials, personal data, or confidential data, cap per-user quotas to prevent abuse, and account for network data transfer charges on downloads. For consuming public content, prefer automatic builds from standardized base images, point builds at internal mirrors, and enforce deployment policy on the resulting images.

3.2Encryption with Customer-Managed Encryption Keys

Encryption with Customer-Managed Encryption Keys (CMEK) in Artifact Registry protects repository contents with a customer-controlled key instead of the default Google-managed key. Google-managed encryption uses a Google-owned and Google-managed key by default and requires no additional configuration. CMEK encrypts an individual repository with a key controlled through Cloud Key Management Service, identified by a full resource path in the form projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY.

The repository depends on the key for ongoing read and write access, so key location, rotation, and organization policy constraints directly affect availability. Repository descriptions and labels are not encrypted, so sensitive data must never be placed in those fields. Choose CMEK when compliance or data-governance policy requires customer control of encryption keys and centralized revocation.

3.3Automatic and On-Demand Vulnerability Scanning

Vulnerability scanning in Artifact Registry matches operating system and language packages against a common vulnerability store. Automatic scanning is enabled by turning on the Container Scanning API for the project, after which billing begins immediately and pushes to Artifact Registry are scanned automatically. Scanning can be allowed or excluded per repository, so a repository with automatic scanning disabled is skipped while other repositories in the same project continue to be scanned. On-Demand Scanning is a separate manual API for shifting checks earlier into the build.

The two scanning modes differ in trigger, freshness, and retention:

A shift-left pipeline uses On-Demand Scanning first and automatic scanning second. Data flows from the builder to the On-Demand Scanning API, then only clean images flow to Artifact Registry, where automatic scanning continues to monitor them for newly disclosed vulnerabilities. For example, Cloud Build can scan an image after it is built and block upload to Artifact Registry when the scan reports vulnerabilities at a specified severity level.

3.4Metadata, Deployment Enforcement, and Centralized Monitoring

Deployment enforcement in Artifact Registry uses Artifact Analysis metadata together with Binary Authorization to block non-compliant images. Artifact Analysis associates metadata with an image through notes, which define a type of check, and occurrences, which record that the check happened for a specific image. People or automated systems add occurrences across source, build, storage, deployment, and runtime phases, such as recording that an image passed integration tests or a vulnerability scan. Binary Authorization then evaluates that metadata against cluster-level policy when deployment to a supported environment is attempted.

A compliant release moves through ordered gates before reaching runtime:

1. Build and scan: The pipeline builds the image and obtains vulnerability metadata from automatic or On-Demand Scanning.
2. Attest: A trusted authority signs an attestation that the image meets severity, provenance, or test thresholds.
3. Admit: Binary Authorization allows deployment only when required attestations are present, and denies images that lack them or come from untrusted registries.
4. Monitor: Binary Authorization Continuous Validation watches active Pods in GKE against platform policy and emits alerts to Logging when running containers become non-compliant.

Security Command Center centralizes the resulting risk across projects by aggregating Artifact Registry findings for images deployed to GKE, Cloud Run services and jobs, and App Engine. It creates findings only for HIGH or CRITICAL severity vulnerabilities, while MEDIUM and LOW findings remain visible in Artifact Registry. Findings can be exported to BigQuery for long-term analysis, and emergency bypass remains possible through breakglass deployments that generate audit log events for SecOps alerting.

3.5Supply Chain Hardening for Integrity Failures

Supply chain hardening in Artifact Registry prevents tag mutation, stale-image reuse, and dependency substitution. Immutable image tags force a tag to always point to the same digest, while deploying strictly by SHA-256 digest (@sha256:...) removes reliance on mutable tags entirely. Cleanup policies delete unversioned, untagged, or stale release-candidate images after a retention period, which reduces storage cost and shrinks the attack surface from legacy software. Virtual repositories with upstream priority that favors internal repositories over public registries protect against dependency confusion attacks.

Provenance and composition evidence extend those controls to open-source dependencies. Assured OSS provides Google-validated packages with verifiable signatures and SLSA build provenance, consumed through remote repositories that point upstream to Assured OSS and virtual repositories that enforce signature checks. Software Bill of Materials (SBOM) generation records package composition for audit and exploitability review when a new CVE is disclosed. Together, immutable references, retention hygiene, prioritized upstreams, and signed provenance ensure that the artifact deployed is the artifact that was built and scanned.

Key Facts

• Artifact Registry cleanup policies include conditional delete, conditional keep, and keep most recent versions using criteria such as older_than, tag state, package_name_prefixes, and keep_count.
• A virtual repository routes client requests to upstream standard and remote repositories in priority order, and prioritizing the private standard repository over the remote public cache mitigates dependency confusion.
• There is no egress charge from Artifact Registry to other Google Cloud services in the same region, while egress from the us multi-region to Canada or South America and from the asia multi-region to Australia is charged.
• Automatic vulnerability scanning continuously updates findings for up to 30 days after push, while On-Demand Scanning results expire after 48 hours and are never updated.
• Binary Authorization allows deployment only for images with required attestations, and Security Command Center creates findings only for HIGH or CRITICAL vulnerabilities from images deployed to GKE, Cloud Run, and App Engine.