The contributor guidelines never defined how a `suite` title has to look, only how an `it` title has to look.
Without a rule five competing schemes grew side by side: `config template | cache config`, `deployment
template (probes)`, `ServiceMonitor template (basic)`, `Test Gateway API httpRoute.yaml` and `Dependency checks
| Customization integrity | valkey`. 24 of the 49 titles started with a lowercase letter, which contradicts the
sentence rule that already applies to the test titles.

More than cosmetics, the missing rule produced three concrete defects:

- `deployment template` was used by both deployment-additional-config.yaml and extraInitContainers.yaml, and
`Init template` by both init_directory_structure.sh.yaml and its rootless counterpart. `helm unittest`
identifies a failing suite by its title, so a failure in either file printed the same header and the report
did not say which file to open.
- deployment/inline-config.yaml was titled `config template`, although it lives in the deployment directory and
asserts on secret_inlineConfig.yaml. It read like a sixth member of the `config template | ...` group.
- persistentVolumeClaim.yaml was titled `PVC template`, using exactly the short name the chart conventions
forbid for files and keys.

All suites now follow `Test <subject> <scenario>`, for example `Test deployment probes` or `Test gateway API
httpRoute`. The subject is the template under test, the scenario is what distinguishes the suite from its
siblings, so every title is unique and sorts next to its related suites. The `Test ` prefix of the Gateway API,
ingress and route suites is kept, because it is the only part of the old schemes that already read as a
sentence; the redundant `.yaml` suffix and the `tests` suffix of the storage class suite are dropped.

The rule is written down in the Unit Tests section of the copilot instructions, so the next suite does not have
to guess which of the five schemes was meant.

Co-authored-by: Copilot <copilot@github.com>

2026-10-03 21:21:46 +02:00

4.6 KiB

Raw Blame History

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.
Render Secret payloads as base64 data and never as stringData. The API server drops stringData and persists everything under data, so Helm's three-way merge cannot prune a key that was removed from the values — the stale key survives every upgrade. For example:

data:
  app.ini: {{ $config | b64enc }}

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.
The suite title follows the pattern Test <subject> <scenario> (e.g. Test deployment probes). It must be unique across all suites, because helm unittest identifies a failing suite by this title.
Each unit test must explicitly set a custom namespace and release name, rather than relying on defaults.
Assert Secret content via data.* with decodeBase64: true and add a notExists assertion for stringData.

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.

4.6 KiB Raw Blame History