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

# Google Artifact Registry

> Connect your own Google Artifact Registry so Ryvn pulls images and charts from it and pushes builds to it, with no service account keys

When your Ryvn hub runs on Google Cloud, you can connect an Artifact Registry in your own Google Cloud project. Ryvn pulls container images and OCI Helm charts from it, and builds can push to it.

Ryvn creates two Google service accounts for your Ryvn organization in the hub's project:

| Service account | What it does | Role you grant |
| - | - | - |
| Reader | Pulls images and charts when environments deploy | `roles/artifactregistry.reader` (required) |
| Publisher | Pushes images and charts that Ryvn builds | `roles/artifactregistry.writer` (optional) |

You grant these accounts access in your project. Ryvn mints short-lived tokens for them and never creates or stores a key.

> [!NOTE]
>
> Google Artifact Registry appears in **Add Registry** only when your hub runs on Google Cloud. On other hubs, use a [generic OCI registry](https://ryvn.ai/docs/deploy/deploy-from-registry.md) instead.

## Before you begin

You need permission to manage registries in Ryvn, and permission to set IAM policy on the Google Cloud project, such as the Project IAM Admin role, `roles/resourcemanager.projectIamAdmin`. The Artifact Registry API must be enabled in the project.

If the project sits inside a VPC Service Controls perimeter that restricts `artifactregistry.googleapis.com`, Ryvn's requests come from outside the perimeter and are denied, even after the grants succeed. Add an ingress rule that lets both service accounts call the Artifact Registry API. The connection test reports a VPC Service Controls denial as a failed check.

## Connect the registry

**1. Add the registry**

Open **Settings > Private Registries**, click **Add Registry**, and select **Google Artifact Registry**. Enter:

* **Registry name**, such as `example-gar`.
* **Project ID** of the project that holds your repositories, such as `example-project`. Use the project ID, not its display name.
* **Location** of the repositories, such as `us-central1` or the multi-region `us`. Ryvn derives the registry host from it, for example `us-central1-docker.pkg.dev`.
* Optional mirrors and environment availability, as for any private registry.

Click **Add Registry**. The project and location cannot change afterwards. Each project and location can be connected once per Ryvn organization.

**2. Grant Ryvn access**

Ryvn opens the registry's page. It shows the reader and publisher service account emails, each with a copy button, and a setup script.

Paste the script into Cloud Shell or any terminal signed in to `gcloud`. It grants the reader `roles/artifactregistry.reader` on the project. That grant is all Ryvn needs to pull.

To let Ryvn builds push to this project as well, select **Also grant publishing (Ryvn builds push to this project)** before you copy or download the script. The command then starts with `GRANT_PUBLISHER=true`, and it also grants the publisher `roles/artifactregistry.writer`. Run a downloaded script with `sh ryvn-artifact-registry-setup.sh`.

The script is safe to rerun. New IAM grants can take a few minutes to apply.

**3. Test access**

Click **Test** on the registry's page. Ryvn runs two checks:

| Check | Passes when | Otherwise |
| - | - | - |
| Reader can list repositories | The reader lists the Docker-format repositories in the project and location. The check shows each repository it found. | A permission error is a **warning**: the script has not run, or you granted access per repository, which this check cannot list. A reader token Ryvn cannot get, a disabled API, a missing project or a VPC Service Controls denial is a **failure**. |
| Publisher can upload | The publisher can upload to at least one of the first eight repositories the reader listed, in name order. | A **warning** when the publisher can upload to none of them, or when the check did not run because the reader check did not pass or the reader found no repositories. A check that times out is also a warning. A publisher token Ryvn cannot get, or a VPC Service Controls denial, is a **failure**. |

The registry is connected when the reader check passes.

## What Ryvn can reach

One reader and one publisher serve your whole Ryvn organization. If you connect several projects, you grant the same two accounts in each one. Every registry token the reader or publisher gets can reach every project you granted that account, not only the registry it was issued for.

Environment availability decides which environments receive pull credentials for a registry. It is not an IAM boundary. To keep two projects apart, keep them out of the same Ryvn organization.

## Deploy from the registry

Reference images and charts by their full Artifact Registry path, for example `us-central1-docker.pkg.dev/example-project/images/api`. Environments where the registry is available get a reader token for it automatically, the same way as for any [private registry](https://ryvn.ai/docs/deploy/deploy-from-registry.md#authenticating-with-private-registry).

## Publish builds to the registry

A service that Ryvn builds from GitHub pushes to [Ryvn Registry](https://ryvn.ai/docs/deploy/ryvn-registry) by default. To push to your Artifact Registry instead, run the setup script with publishing granted, then bind the service to the registry.

> [tab] Dashboard
>
> Open the service, go to **Settings > Build & Deploy**, and pick your registry in **Publish registry**. Enter the destination, then click **Save**:
>
> * For a server or job, **Image repository**, such as `us-central1-docker.pkg.dev/example-project/images/api`, without a tag.
> * For a Helm chart, **Chart repository**, such as `example-project/charts`.

> [tab] YAML
>
> ```yaml theme={null}
> kind: Service
> metadata:
>   name: api
> spec:
>   type: server
>   repo: example-org/api
>   registry: example-gar
>   image: us-central1-docker.pkg.dev/example-project/images/api
>   build:
>     context: .
>     dockerfile: Dockerfile
> ```

The destination must live in the registry's project and location:

* An image must be `<location>-docker.pkg.dev/<project>/<repository>/<name>`, with the registry's location and project.
* A chart repository must start with `<project>/<repository>`.

Ryvn refuses to save any other destination. Create the repository in Artifact Registry first. Ryvn checks it before each build and stops with a clear error when the repository does not exist, or when the publisher cannot reach it because the optional write grant was not run.

### Build limits

* **Builds have one hour to push.** The publisher's token lasts one hour from the start of the build. A build that runs longer fails when it pushes.
* **Base images need read access too.** The build signs in to the registry host as the publisher. If a Dockerfile's `FROM` image lives in another Artifact Registry project at the same host, the publisher needs `roles/artifactregistry.reader` in that project, or the build fails.

## Revoke access

Remove the grants in your project. Copy the service account emails from the registry's page in Ryvn:

```bash theme={null}
gcloud projects remove-iam-policy-binding example-project \
  --member="serviceAccount:READER_EMAIL" \
  --role=roles/artifactregistry.reader

gcloud projects remove-iam-policy-binding example-project \
  --member="serviceAccount:PUBLISHER_EMAIL" \
  --role=roles/artifactregistry.writer
```

Ryvn loses access once Google applies the change, usually within a few minutes. Ryvn never deletes the service accounts, so you can grant them again later.