volker.raschekandCopilot
eeacda2a25
The chart conventions demand camelCase file names, forbid short names like `svc` and require the unit tests to
mirror the template structure. The unit tests followed none of that consistently. Four casings existed side by
side - camelCase (extraInitContainers.yaml), kebab-case (checksum-annotations.yaml), a snake and kebab mix
(init_directory_structure.sh-rootless.yaml) and all caps (HA.yaml) - so there was no pattern to copy when
adding a suite, which is how the inconsistency kept growing.
Three groups of problems are fixed:
- svc-configuration.yaml used exactly the short name the conventions forbid for files and keys.
- Several file names repeated their own directory, for example deployment/deployment-additional-config.yaml and
metric-secret/metrics-secret-servicemonitor-disabled.yaml, which names the subject three times. The directory
already carries that information, so the file name now only carries the scenario. The default scenario of a
template is named basics.yaml.
- Four suites lived in a directory of a template they do not assert on. They were filed under deployment/
because the deployment is rendered as a side effect, not because it is the subject:
deployment/deprecations.yaml -> deprecation/deployment.yaml
deployment/inline-config.yaml -> config/inlineConfig.yaml
deployment/storage-class-configuration.yaml -> persistentVolumeClaim/storageClass.yaml
deployment/svc-configuration.yaml -> service/configuration.yaml
storage-class-configuration.yaml is the clearest case: a persistentVolumeClaim directory already existed next
to it. The suite titles of the two suites whose subject changed are adjusted accordingly.
The Makefile passed `--file unittests/helm/values-conflicting-checks.yaml`, but that file does not exist in the
tree. `helm unittest` ignores a missing path without a warning, so the flag has been dead for an unknown amount
of time while still suggesting the checks run. It is removed; the `unittests/helm/**/*.yaml` glob would pick
the file up anyway if it ever returns.
The naming rule is written down in the copilot instructions, together with the constraint that the glob matches
only a single directory level, so a suite can never be placed directly in unittests/helm/.
All 49 suites and 267 tests still pass.
Co-authored-by: Copilot <copilot@github.com>
76 lines
5.1 KiB
Markdown
76 lines
5.1 KiB
Markdown
# Gitea Helm Chart — Copilot Instructions
|
|
|
|
## Project Overview
|
|
|
|
Kubernetes Helm chart for deploying [Gitea](https://gitea.com). Uses Go/Helm templating (`templates/`), YAML values (`values.yaml`), and includes sub-charts for PostgreSQL, PostgreSQL-HA, Valkey, and Valkey-cluster.
|
|
|
|
## Build & Test
|
|
|
|
```bash
|
|
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](https://docs.renovatebot.com/modules/manager/helm-values/#additional-information) pattern from renovatebot. Ensure that the attributes `registry`, `repository` and `tag` are available as part of the dict `image`. For example:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
data:
|
|
app.ini: {{ $config | b64enc }}
|
|
```
|
|
|
|
### Unit Tests
|
|
|
|
- Helm unit tests live in `unittests/helm/` mirroring the template structure. A suite belongs into the directory of the template it asserts on, never into the directory of a template it only renders as a side effect.
|
|
- Test files are YAML using the [helm-unittest](https://github.com/helm-unittest/helm-unittest) format.
|
|
- Name test files in camelCase after the scenario they cover (e.g. `signingEnabled.yaml`), use `basics.yaml` for the default scenario and do not repeat the directory name in the file name. The `make helm/unittest` glob only matches one directory level, so every suite must live in a subdirectory.
|
|
- 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](https://www.conventionalcommits.org/en/v1.0.0/) 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.
|