homelab-gitops/docs/chart-ownership.md

Helm chart ownership and promotion

This repository contains cluster policy and values, not application workload implementations. Deployments, StatefulSets, Services, ports, probes, mount paths, and configuration wiring belong to a published upstream or maintained Helm chart outside this repository.

Each independently versioned application has one chart and one Argo CD Application. This includes each Artcraft application: WordCraft, GridCraft, DeckCraft, PhotoCraft, LightCraft, VectorCraft, FilmCraft, EffectCraft, DesignCraft, FigCraft, PdfCraft, SoundCraft, and CADCraft are separate releases, not one suite chart. They share the artcraft namespace but do not share Kubernetes resource ownership. Their static upstream release bundles and nginx configuration are baked into distinct immutable images; pods never download application code at startup.

Maintained chart repositories set Chart.yaml.appVersion to the tested application/image version. The chart repository's base Git tag follows the application release, not an invented chart v1.0.0. CI derives the chart package version from Git:

• for Diun 4.33.0, tag v4.33.0 produces chart 4.33.0;
• the next commit produces a unique version such as 4.33.0-1-g41627abcdef.

appVersion remains the exact upstream/image version. If that version is a date, commit hash, or other non-SemVer string, choose and document a SemVer-compatible chart tag derived from it; do not silently substitute 1.0.0. Keep the Git tag equal to the upstream release even when the chart package needs a SemVer mapping: ImmichFrame tag v1.0.39.0 becomes chart 1.0.39-0 while its appVersion and default image tag remain v1.0.39.0.

The target layout is one repository per maintained chart, with tags such as v4.33.0. Existing shared repositories are legacy, not a template for new charts.

The hash is retained to prevent package-version collisions. CI publishes to https://brunner.ninja/charts, then uses GITOPS_TOKEN to update only the matching Argo Application's exact Helm targetRevision. Argo CD performs the deployment; chart CI never receives Kubernetes credentials.

Migration completion check

For a maintained chart, keep the chart and CI in its own source repository. Before activating a new Argo Application, publish the chart and verify its exact version in the Gitea Helm index. It is safe to commit the Application, AppProject, and values files first without listing the Application in bootstrap/kustomization.yaml; this lets chart CI update its version without creating an Argo Application that points to a missing chart. Activate it after publication, then verify both homelab-bootstrap and the new Application are Synced and Healthy.

If Gitea Actions fails, inspect the failed job's steps and logs before asking for help or changing the workflow. On arschrock, Gitea's local admin CLI is available through sudo -n -u gitea /usr/bin/gitea -c /etc/gitea/app.ini; use its admin user generate-access-token --help command to create scoped package and GitOps tokens. Set repository Actions secrets through PUT /api/v1/repos/{owner}/{repo}/actions/secrets/{name} without printing raw tokens. The workspace AGENTS.md has the full diagnostic procedure. Complete the CI rerun, chart publication, GitOps promotion, Argo rollout, ready containers, exact image tag, and PVC UID/volume check before declaring a migration done.

GitOps values may select namespaces, hostnames, ingress integration, existing claims or storage classes/sizes, resource sizing, replica counts, monitoring labels, and names of existing Secrets. They must not duplicate chart-owned image versions or resource topology.