helm-gitea/.github/copilot-instructions.md

Gitea Helm Chart — Copilot Instructions

Project Overview

Kubernetes Helm chart for deploying Gitea. Uses Go/Helm templating (templates/), YAML values (values.yaml), and includes sub-charts for PostgreSQL, PostgreSQL-HA, Valkey, and Valkey-cluster.

Build & Test

make missing-dot       # Check if the @param annotations are missing a trailing dot.
make readme            # Regenerate README.md parameter table + lint + link checker
make helm/unittest     # Run Helm unit tests (helm-unittest plugin required)
make bash/unittest     # Run bash/bats script tests (requires git submodule init)

Always run make readme after changing values.yaml @param annotations. Always run make helm/unittest after changing templates or unit tests.

Conventions

values.yaml

• Use ## @param path.to.key Description annotations for every user-facing value. These drive the auto-generated README parameter table.
• Property ordering within a resource block: enabled, annotations, labels first, then type-specific fields.
• Top-level keys are sorted alphabetically within their section group.
• Use Helm Values pattern from renovatebot. Ensure that the attributes registry, repository and tag are available as part of the dict image. For example:

image:
  registry: docker.io
  repository: library/busybox
  tag: 0.1.0

Templates

• Helm templates live in templates/. Helpers live in templates/_helpers.tpl.
• Use camelCase for all files and variables (e.g httpRoute, backendTLSPolicy, gatewayAPI, statefulSet).
• Use include "gitea.fullname" for naming resources.
• Use fail for required-value validation with clear error messages referencing the full values path.
• Ensure, that the attributes annotations, labels, name and namespace are alphabetically sorted.
• Render all attributes, even if they are empty, to prevent drift in Argo CD. For example, labels must be rendered, while annotations are defined as yaml:"annotations,omitempty".
• Use plural for *.tpl files, because they may contain functions for multiple resources of the same kind (e.g. _services.tpl for httpService.yaml or sshService.yaml, _backendTLSPolicies.tpl for backendTLSPolicy.yaml).
• Use as prefix of YAML files the resource kind (e.g., deployment.yaml for Deployment resources). If there are multiple resources of the same kind, use a descriptive suffix (e.g., deployment_metrics.yaml for a Deployment related to metrics).
• Short names like pvc for Persistent Volume Claims or svc for Services are not allowed in file names or key names.

Unit Tests

• Helm unit tests live in unittests/helm/ mirroring the template structure.
• Test files are YAML using the helm-unittest format.
• Each test must set all required values explicitly — do not rely on cross-test state.
• The values.yaml file must pass yamllint. The configuration is in .yamllint.yaml. Use make yamllint to run the linter.
• The title of the unit test should clearly describe the scenario being tested. As title must be use a short sentence starting with a capital letter and ending without a period.
• Each unit test must explicitly set a custom namespace and release name, rather than relying on defaults.

Commits & PRs

• Follow Conventional Commits for PR titles and commit messages (e.g. feat:, fix:, refactor:, docs:, style:).
• See CONTRIBUTING.md for full PR requirements.
• Explain in detail why a change is needed, not just what the change is. Include links to relevant issues, PRs, or external references.
• Add co-authors for any contributions that are not your own. Use the Co-authored-by: trailer in the commit message.

Documentation

• docs/ contains topic-specific guides (e.g. gateway-api.md, ha-setup.md).
• README.md parameter tables are auto-generated — never edit them manually.