volker.raschekandCopilot
fef4190a74
Bash / bash-unittest (push) Successful in 14s
Bash / shellcheck (push) Successful in 20s
changelog / changelog (push) Successful in 16s
Helm / helm-lint (push) Successful in 15s
Helm / helm-unittest (push) Successful in 32s
Markdown linter / markdown-lint (push) Successful in 15s
Markdown linter / markdown-link-checker (push) Successful in 56s
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>
75 lines
4.6 KiB
Markdown
75 lines
4.6 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.
|
|
- Test files are YAML using the [helm-unittest](https://github.com/helm-unittest/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](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.
|