> ## Documentation Index
> Fetch the complete documentation index at: https://docs.backline.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GCP Artifact Registry Integration

> Scan container images hosted in Google Cloud at gcr.io and pkg.dev addresses

## Overview

The GCP Artifact Registry integration gives Backline read access to the container images your applications run from Google Cloud, so those images are analyzed for vulnerabilities.

You supply one Google service account key. Backline uses it for every Google-hosted image address it encounters for your tenant — you do not list your repositories, so images in repositories your teams create later are covered without any change in Backline.

<Note>
  This integration is for **container images**. Private **packages** hosted on Google Cloud are a separate integration, [GCP Package Registry](/integrations/gar) — which was itself named "GCP Artifact Registry" until this release. See [Two Google integrations](#two-google-integrations) below.
</Note>

## What You Can Do

With the GCP Artifact Registry integration, Backline can:

* Analyze image layers for vulnerabilities
* Detect security issues in dependencies
* Track image security across versions
* Monitor compliance with security policies

<Tip>
  Where an image carries no source provenance, Backline asks you to map it to its repository and Dockerfile once. See [Image to Code Mapping](/get-started/vulnerabilities/image-to-code).
</Tip>

## Covered Image Addresses

Backline treats these as Google-hosted container image addresses and resolves them through this integration:

| Address | Example |
| - | - |
| `gcr.io` and its regional hosts `us.gcr.io`, `eu.gcr.io`, `asia.gcr.io` | `gcr.io/my-project/my-service:1.4.0` |
| Any `<region>-docker.pkg.dev` host | `us-central1-docker.pkg.dev/my-project/my-repo/my-service:1.4.0` |

You do not need to re-tag images that still use a `gcr.io` address — both address families are covered by the same connection.

<Note>
  The package address families `<region>-npm.pkg.dev`, `<region>-python.pkg.dev` and `<region>-go.pkg.dev` are **not** container image addresses. They belong to the [GCP Package Registry](/integrations/gar) integration.
</Note>

## Public Images Need No Connection

An image at a Google-hosted address that can be pulled without credentials — such as a public distroless base image — is analyzed whether or not you have this integration connected, and whatever state that connection is in. A publicly pullable Google-hosted image requires the same setup as a publicly pullable Docker Hub image: none.

Connect this integration for the images that are **private** to your Google Cloud projects.

## Prerequisites

Before connecting GCP Artifact Registry, ensure you have:

* A Google Cloud project hosting the container images your applications run
* The Artifact Registry API enabled for that project
* Permissions to create service accounts, assign roles, and create service account keys

## Enabling the Artifact Registry API

<Steps>
  <Step title="Navigate to the API Library">
    Go to the [Artifact Registry API page](https://console.cloud.google.com/apis/library/artifactregistry.googleapis.com) in the Google Cloud Console.
  </Step>

  <Step title="Select Your Project">
    Select the project hosting your container images.
  </Step>

  <Step title="Enable the API">
    Click **Enable**.

    <Note>
      Allow a few minutes for Google to propagate the enablement before proceeding.
    </Note>
  </Step>
</Steps>

## Creating a Service Account

<Steps>
  <Step title="Navigate to Service Accounts">
    Go to the [Service Accounts page](https://console.cloud.google.com/iam-admin/serviceaccounts) in the Google Cloud Console and select your project.
  </Step>

  <Step title="Create the Service Account">
    Click **Create service account**, give it a unique name and ID, then click **Create and Continue**.
  </Step>

  <Step title="Assign Roles">
    Grant the service account:

    1. **Artifact Registry Reader** — read access to images in Artifact Registry
    2. **Storage Object Viewer** — only if you use `gcr.io` addresses (see below)

    Click **Continue**, then **Done**.
  </Step>

  <Step title="Generate a JSON Key">
    1. Open the service account you just created
    2. Go to the **Keys** tab
    3. Click **Add Key** → **Create new key**
    4. Select **JSON** and click **Create**

    The JSON key file downloads automatically.

    <Warning>
      Store the JSON key securely. It grants read access to the container images in the projects where you granted it roles.
    </Warning>
  </Step>
</Steps>

## Required Permissions

| Role | Purpose |
| - | - |
| **Artifact Registry Reader** | Read images at `<region>-docker.pkg.dev` addresses, and images in Artifact Registry served under `gcr.io` |
| **Storage Object Viewer** | Required for legacy `gcr.io` images, whose layers are stored in Cloud Storage buckets rather than in Artifact Registry |

<Tip>
  If every image you run is at a `<region>-docker.pkg.dev` address, **Artifact Registry Reader** alone is enough. Add **Storage Object Viewer** if any of your image references still use a `gcr.io` host.
</Tip>

Grant the roles on every project whose images your applications run. One connection covers whatever its key can read, so a key that reaches only one project covers only that project's images.

## Connecting GCP Artifact Registry

<Steps>
  <Step title="Go to Integration Hub">
    In Backline, navigate to **Integrations** from the main menu.
  </Step>

  <Step title="Select GCP Artifact Registry">
    Find and click on the **GCP Artifact Registry** integration card, among the container registries.
  </Step>

  <Step title="Paste the Service Account JSON">
    Paste the full contents of the JSON key file into the **Service Account JSON** field. This is the only field.
  </Step>

  <Step title="Test Connection">
    Click **Test Connection** to check that the key authenticates with Google.
  </Step>

  <Step title="Save">
    Click **Save** to complete the integration.
  </Step>
</Steps>

<Note>
  Backline supports one GCP Artifact Registry connection per tenant. To cover images in more than one Google Cloud project, grant that one service account the roles above on each project.
</Note>

## Connection Health

If Google-hosted images stop producing findings, open the integration and click **Test Connection**. A failed test reports the reason Google gave.

## After Connection

Once GCP Artifact Registry is connected, Backline will:

1. Authenticate with the service account key each time it reads one of your Google-hosted images
2. Analyze the images your applications reference at the covered addresses
3. Report findings, inventory, and base-image attribution for those images
4. Suggest a safer base image tag where a newer tag resolves the reported vulnerabilities

## Managing the Integration

### Rotating the Service Account Key

1. Generate a new JSON key in the Google Cloud Console (following the steps above)
2. Open the **Integration Hub** and click on the **GCP Artifact Registry** integration
3. Paste the new key into **Service Account JSON**, then **Test Connection** and **Save**
4. Delete the old key from the Google Cloud Console

<Tip>
  Regularly rotating service account keys is a security best practice.
</Tip>

### Disconnecting

1. Go to the **Integration Hub**
2. Click on the **GCP Artifact Registry** integration
3. Select **Disconnect**
4. Confirm your choice

<Warning>
  Disconnecting stops Backline from reading private images in your Google Cloud projects, so those images will no longer produce findings. Publicly pullable Google-hosted images are unaffected.
</Warning>

## Two Google Integrations

Backline has two separate Google Cloud integrations, each with its own credential, status, and lifecycle. You can hold both at once.

| Integration | Purpose |
| - | - |
| **GCP Artifact Registry** (this page) | Container images at `gcr.io` and `<region>-docker.pkg.dev` addresses |
| [**GCP Package Registry**](/integrations/gar) | Private npm, PyPI, and Go packages at `<region>-npm.pkg.dev`, `<region>-python.pkg.dev`, and `<region>-go.pkg.dev` addresses |

## Troubleshooting

### Test Connection Fails

* Verify the JSON key file was pasted in full and is not truncated
* Check that the service account still exists and the key has not been revoked or deleted in the Google Cloud Console

### Connected, but Images Produce No Findings

* Verify the service account has **Artifact Registry Reader** on the project hosting the images
* For `gcr.io` addresses, verify it also has **Storage Object Viewer**
* Confirm the Artifact Registry API is enabled for the project
* Confirm the image address is one of the [covered addresses](#covered-image-addresses)
* Click **Test Connection**; if it fails, the reported error names the reason Google gave