Container Registry

GitRiver has a built-in Docker Registry compatible with OCI Distribution Spec v2. No separate service is needed - images are stored directly in the platform, linked to a repository.

Why

• Store Docker images alongside your code, in the same repository
• Automatically build and publish images from CI/CD
• Control access through the same permissions as the repository
• No dependency on external services

---

Getting Started

1. Get a Token

To access the registry you need a token. You can use:

• Personal token (prefix gtr_pat_) - create in Settings -> Tokens with registry permissions
• Deploy token (prefix gtr_deploy_) - create in repository settings, Deploy Tokens section
• CI token (CI_JOB_TOKEN) - automatically available inside CI jobs

2. Log In

docker login git.example.com -u your_username -p gtr_pat_xxxxx

Use the token instead of a password. The login is your GitRiver username.

3. Build and Push an Image

docker build -t git.example.com/owner/repo:v1.0 .
docker push git.example.com/owner/repo:v1.0

4. Pull an Image

docker pull git.example.com/owner/repo:v1.0

Tag Format

git.example.com/{owner}/{repository}[/{image}]:{tag}

Arbitrary nesting is supported: git.example.com/owner/repo/frontend/nginx:latest.

---

Using in CI/CD

Ready-made variables for working with the registry are available in CI jobs:

jobs:
  build:
    image: docker:latest
    steps:
      - run: |
          docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
          docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
          docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

Variable	Value
CI_REGISTRY	Registry address (e.g., git.example.com)
CI_REGISTRY_IMAGE	registry/owner/repo
CI_REGISTRY_USER	Login for authentication
CI_REGISTRY_PASSWORD	Token (= CI_JOB_TOKEN)

---

Viewing Images

1. Open the repository in GitRiver
2. Go to the tab where images are displayed (in the repository menu)
3. You’ll see a list of images with tags, sizes, and dates

For each image, details are available: layers, configuration, platforms (for multi-arch).

---

Tag Immutability Rules

Problem: someone overwrote the latest or v1.0 tag with a new image, and the deployment broke.

Solution: immutability rules. Tags matching the pattern cannot be overwritten.

Configuration: Repository Settings -> Registry -> Tag Rules.

• Specify a glob pattern: v*, release-*, latest
• Check “Immutable”
• After that, docker push with an existing tag will return an error

---

Retention Policies

Over time, images accumulate and take up space. Retention policies automatically remove old tags.

Configuration: Repository Settings -> Registry -> Retention Policies.

• Keep last N - retain only the N most recent tags
• Delete older than N days - remove tags older than the specified age
• Image pattern - which images the rule applies to

---

Garbage Collection

After deleting tags, blobs (image layers) remain on disk. To free up space, run garbage collection.

How: Administration -> Storage -> “Cleanup” button.

You can set up automatic scheduled runs on the same page.

---

Storage

By default, images are stored in the filesystem (in the git_repos_path directory). For production, S3-compatible storage is recommended - see the Configuration -> S3 section.

Switching between filesystem and S3: Administration -> Storage. The “Test” button checks the connection without saving.

---

Vulnerability Scanning

GitRiver can display image vulnerability scanning results. This requires an external scanner (e.g., Trivy) that uploads results in SARIF format.

Enabling: registry_scan_enabled = true in config + path to Trivy (trivy_path).

Results are displayed in the image detail view.

This is a Pro feature: viewing scan results is available to users with a Pro seat.