OCIR basics: push/pull, private repos, auth tokens

Problem

Oracle Cloud Infrastructure Registry (OCIR) is simple once you know the rules, and confusing until then. Most failures come from the same few places: a wrong region endpoint, a wrong username format, or an expired token.

I wanted a short reference that gets a private repository working and keeps it private.

Options and trade-offs

• Public repositories: easy to share, and only suitable for images that are safe for anyone to pull.
• Private repositories with auth tokens: the standard approach, and it needs good token hygiene.
• Short-lived or bearer-style credentials: possible for pipelines, with more setup to maintain.

My recommendation

Use private repositories and user auth tokens. Create the repository explicitly in the compartment that owns it, instead of letting a first push create it. Keep the regional endpoint and the username format written down where the team can find them.

Worked example

Log in with the registry endpoint for your region. The username begins with your tenancy namespace. If your user belongs to a non-default identity domain or is federated, the username format changes, so check the documentation for your case.

docker login <region-key>.ocir.io
# Username: <tenancy-namespace>/<username>
# Password: <auth-token>
 
oci artifacts container repository create \
  --compartment-id <compartment_ocid> \
  --display-name myteam/myapp \
  --is-public false
 
docker tag myapp:1.4.2 <region-key>.ocir.io/<tenancy-namespace>/myteam/myapp:1.4.2
docker push <region-key>.ocir.io/<tenancy-namespace>/myteam/myapp:1.4.2

And the policies, kept separate for people who browse and people who manage:

Allow group image-viewers to inspect repos in tenancy
Allow group image-publishers to manage repos in compartment registry

I tag with a version, not latest, so a rollback is a one-line change. A user can hold only a small number of auth tokens, so plan token replacement for your pipelines before it is urgent.

Checklist

1. Know the endpoint for your region and use it consistently.
2. Use the tenancy namespace in the username, and the auth token as the password.
3. Create repositories explicitly and confirm they are private.
4. Set separate policies for viewing and managing repositories.
5. Tag images with versions, and avoid latest in production.
6. Set a retention rule, and watch pulls for surprises.

Where this doesn't apply

Air-gapped clusters cannot reach OCIR directly. They need a mirrored or internal registry instead.

One honest limitation

Auth tokens expire or get replaced, and a stale token in a pipeline fails at the worst time. Treat it like any other credential and give it an owner and a rotation date.

Sources

• OCI Documentation: Pushing Images Using the Docker CLI
• OCI Documentation: Logging in to Oracle Cloud Infrastructure Registry
• OCI Documentation: Required Policies for Container Registry