Skip to main content
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: You grant these accounts access in your project. Ryvn mints short-lived tokens for them and never creates or stores a key.
Google Artifact Registry appears in Add Registry only when your hub runs on Google Cloud. On other hubs, use a generic OCI registry 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: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.

​
Publish builds to the registry

A service that Ryvn builds from GitHub pushes to 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.
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.
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:
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.