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. CI derives the chart package version from Git:

• tag v1.0.0 produces chart 1.0.0;
• the next commit produces a unique version such as 1.0.0-1-g41627abcdef.

The target layout is one repository per maintained chart, with tags such as v1.0.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 can create scoped tokens for repository Actions secrets; see the workspace AGENTS.md for the command, API path, and secret handling rules. 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.