# 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.