Registry and Catalog

Complete guide to Helm chart registry, Kustomize bases, manifest bundles, OCI distribution, versioning, and credential management.

The Registry and Catalog is a centralized marketplace for reusable deployment artifacts shared across all projects in your organization. It provides a governed, versioned repository for Helm charts, Kustomize bases, and manifest bundles — ensuring consistency, auditability, and safe reuse across teams.

Key Concept

Think of the catalog as your organization's internal artifact store. Author once, publish immutable versions, and consume safely from any project. Every published version is permanent and auditable.

Three Artifact Types

GitOpsHQ supports three types of reusable deployment artifacts:

Artifact Type	Description	Use Case
Helm Charts	Parameterized Kubernetes templates with values	Complex applications with configurable deployments
Kustomize Bases	Reusable Kustomize configurations	Standardized base configurations with overlay support
Manifest Bundles	Collections of raw Kubernetes YAML	Simple, static resource collections

Loading diagram…

Helm Charts

Helm charts are the most powerful artifact type, supporting full parameterization through Go templates and values files.

A typical chart layout in the registry:

Chart.yaml

values.yaml

values.schema.json

_helpers.tpl

deployment.yaml

service.yaml

ingress.yaml

hpa.yaml

serviceaccount.yaml

Source Types

Git Source

Charts hosted directly in GitOpsHQ's internal Git repository. This is the recommended source for charts authored by your organization.

Full editing via the built-in Monaco editor
Version control with commit history
Integrated chart scaffolding
Direct publishing to the embedded OCI registry

Chart Structure:
├── Chart.yaml          # Chart metadata
├── values.yaml         # Default values
├── templates/
│   ├── _helpers.tpl    # Template helpers
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   └── hpa.yaml
└── README.md

OCI Source

Charts pulled from an external OCI-compliant registry (e.g., Docker Hub, AWS ECR, Google Artifact Registry, GitHub Packages).

Requires OCI credentials configured in Org Settings
Versions are discovered automatically from the remote registry
Read-only — cannot edit charts from external registries
Supports helm pull and helm push compatible registries

External URL

Charts referenced by URL, useful for public chart repositories.

Point to any HTTP(S) URL serving a chart archive
Version tracking via the external source
No editing capabilities — reference only
Suitable for well-known public charts

Chart Editor

The chart editor provides a full IDE experience built on Monaco (the same engine as VS Code):

File tree sidebar with search and create/delete operations
Syntax highlighting for YAML, Go templates, and Helm-specific syntax
Multi-file editing with tab management
Chart scaffolding: Generate a complete chart structure with sensible defaults via a single action
Preview panel: Render template output with sample values
Validation: Real-time YAML syntax checking

Version Publishing

Edit Chart Files

Use the Monaco editor to author or update your chart templates, values, and metadata.

Review Changes

Inspect all pending changes before publishing. The editor shows a diff of modifications.

Set Version Tag

Enter a version tag (semantic versioning recommended, e.g., 1.2.0). The version must be unique — you cannot overwrite an existing version.

Publish

Click Publish Version. The chart snapshot is frozen as an immutable artifact. It cannot be modified or deleted after publishing.

Immutability Rule

Published versions are permanently immutable. You cannot modify, overwrite, or delete a published version. If you need to fix an issue, publish a new version instead. This guarantees that any project referencing version 1.2.0 always gets the exact same artifact.

Version History

Browse all published versions with:

Version tag and publication timestamp
Author who published the version
Commit reference (for Git-sourced charts)
Read-only file browser for any historical version
Diff between versions to see what changed

Kustomize Bases

Kustomize bases provide reusable configuration foundations that project teams customize with overlays.

Feature	Description
Base Editor	Monaco-based editing of `kustomization.yaml` and resource files
Resource Management	Add, edit, and remove resources from the base
Version Publishing	Same immutable versioning as Helm charts
Version History	Browse and compare published versions

A typical Kustomize base structure:

kustomize-base/
├── kustomization.yaml
├── deployment.yaml
├── service.yaml
├── configmap.yaml
└── patches/
    └── resource-limits.yaml

Projects consume these bases by referencing a specific version in their Kustomize overlays, adding their own patches and transformations on top.

Manifest Bundles

Manifest bundles are collections of raw Kubernetes YAML files grouped as a single deployable unit.

Feature	Description
Bundle Editor	Monaco-based editing of multiple manifest files
File Management	Add, rename, and remove files within the bundle
Version Publishing	Immutable versioned snapshots
Version History	Full history with diff support

Manifest bundles are ideal for:

Static infrastructure resources (namespaces, RBAC, network policies)
CRD installations
Operator deployments that don't need parameterization
One-off migration resources

UI Routes

Route	Purpose
`/charts`	Helm chart catalog listing
`/charts/:name/editor`	Chart file editor (Monaco)
`/charts/:name/versions`	Chart version history
`/kustomize-bases`	Kustomize base catalog listing
`/kustomize-bases/:name/editor`	Kustomize base editor
`/kustomize-bases/:name/versions`	Kustomize base version history
`/manifest-bundles`	Manifest bundle catalog listing
`/manifest-bundles/:name/editor`	Bundle editor
`/manifest-bundles/:name/versions`	Bundle version history

API Routes

Route	Purpose
`/api/v2/org-charts`	List and manage Helm charts
`/api/v2/org-charts/{name}/versions`	Publish and list chart versions
`/api/v2/org-kustomize-bases`	List and manage Kustomize bases
`/api/v2/org-kustomize-bases/{name}/versions`	Publish and list Kustomize base versions
`/api/v2/org-manifest-bundles`	List and manage manifest bundles
`/api/v2/org-manifest-bundles/{name}/versions`	Publish and list manifest bundle versions
`POST /api/v2/workloads/{id}/upgrade`	Trigger a workload upgrade

OCI Distribution

GitOpsHQ includes an embedded OCI-compliant registry that serves as the distribution layer for all published artifacts.

How It Works

Loading diagram…

OCI Workflow

The embedded registry is fully compatible with the standard Helm OCI workflow:

# Authenticate with the registry
helm registry login gitopshq.example.com \
  --username org-token \
  --password <registry-token>

# Pull a chart from the registry
helm pull oci://gitopshq.example.com/charts/my-chart --version 1.2.0

# Push a chart to the registry (requires push-scoped token)
helm push my-chart-1.3.0.tgz oci://gitopshq.example.com/charts/

Rate Limiting

All /v2/ OCI endpoints are rate-limited by the OCIRateLimitMiddleware to protect the registry from abuse:

Scope	Limit
All `/v2/` endpoints (pull, push, catalog)	300 requests/minute per IP address

Rate limiting is applied uniformly across all OCI operations and is tracked by client IP address, not by token.

Registry Tokens

Registry tokens provide authentication for OCI operations. They are created in Org Settings → Registry.

Field	Description
Name	Descriptive token name (e.g., `ci-pipeline-pull`)
Scope	Operations allowed: `pull`, `push`, or `pull+push`
Expiration	Optional expiration date
Created By	User who created the token
Last Used	Timestamp of last token usage

Navigate to Org Settings

Go to Organization Settings → Registry → Tokens.

Create Token

Click Create Token, enter a name, and select the scope (pull, push, or both).

Copy Token Value

The token value is displayed only once at creation time. Copy it immediately and store it securely.

Configure Consumers

Use the token in CI/CD pipelines, cluster agents, or external tools that need registry access.

One-Time Display

Registry tokens are shown only at creation time. If you lose the token value, you must revoke it and create a new one. There is no way to retrieve an existing token's value.

OCI Credentials

OCI credentials allow GitOpsHQ to access external OCI registries for pulling charts from third-party sources.

Field	Description
Registry Host	The OCI registry hostname (e.g., `ghcr.io`, `registry.example.com`)
Username	Registry username or service account
Password/Token	Registry password or access token (encrypted at rest)
Test Result	Connectivity test status

Version	Meaning
`1.0.0`	Initial stable release
`1.1.0`	Backward-compatible feature addition
`1.1.1`	Backward-compatible bug fix
`2.0.0`	Breaking change

While semver is recommended, any unique string is accepted as a version tag. Versions are displayed in chronological order (most recent first) in the version history.

Troubleshooting

Error	Meaning	Resolution
`409 version already exists`	Attempting to publish a version tag that is already taken	Choose a new, unique version tag
`403 DENIED`	Token lacks the required scope	Verify token has `push` scope for push operations
`401 invalid registry token`	Authentication failure	Check token is not expired or revoked
`400 DIGEST_INVALID`	Upload integrity check failed	Retry the push operation
`413 SIZE_INVALID`	Artifact exceeds size limit	Reduce chart/bundle size or contact support
`404 MANIFEST_UNKNOWN`	Referenced version does not exist	Verify the version tag and chart name
`404 NAME_UNKNOWN`	Referenced chart does not exist	Verify the chart name in the registry

Best Practices

Keep charts in the org registry — Centralized governance and audit trail for all deployment artifacts
Use immutable versions — Never rely on mutable tags; always reference specific version numbers
Test charts in development — Validate chart rendering and deployment in dev environments before promoting
Rotate registry tokens — Set expiration dates on tokens and rotate them regularly
Minimize OCI credential scope — Use least-privilege credentials for external registry access
Publish release notes — Document what changed in each version for downstream consumers
Scaffold new charts — Use the built-in chart scaffold to start with a well-structured template
Review before publishing — Once published, a version is permanent; review carefully before clicking Publish