Story (Required)

As a Pipelines-as-Code user or developer trying to define and manage Repository Custom Resources I want clear validation, documentation, and tooling support for my Repository resources so I can avoid configuration errors and understand the resource structure easily.

Describes high level purpose and goal for this story. Answers the questions: Who is impacted, what is it and why do we need it? How does it improve the customer’s experience?

This story impacts users and developers working with Pipelines-as-Code Repository resources. By adding OpenAPI schema validation to the Repository CRD, we provide explicit structure and constraints. This allows client-side tooling (like kubectl and IDEs) to perform validation and offer better assistance (autocompletion, documentation tooltips). This significantly improves the user experience by catching configuration errors early and making the resource definition clearer and easier to use.

Background (Required)

Describes the context or background related to this story

Kubernetes Custom Resource Definitions (CRDs) support embedding OpenAPI v3 schema validation. This schema serves as a machine-readable contract for the resource structure, enabling client-side validation and tooling support. Currently, the Pipelines-as-Code Repository CRD lacks comprehensive schema validation, which can lead to user errors and a less optimal developer experience when manually creating or editing Repository resources.

Out of scope

Defines what is not included in this story

• Implementing complex validation logic that cannot be expressed purely through OpenAPI schemas (these are typically handled by admission webhooks).
• Adding OpenAPI schema validation to other Pipelines-as-Code CRDs beyond the Repository resource.

Approach (Required)

Description of the general technical path on how to achieve the goal of the story. Include details like json schema, class definitions
1. Enhance the Go types (`pkg/apis/pipelinesascode/v1alpha1/types.go`) with `+kubebuilder` markers. These markers define the OpenAPI schema properties such as field types, descriptions, required fields, pattern validations, enum values, minimum/maximum values, and print columns for `kubectl get`.
2. Develop a script (`hack/update-schemas.sh`) that utilizes `controller-gen` to read the `+kubebuilder` markers from the Go types and generate the corresponding OpenAPI schema in YAML format. The script will use `yq` to merge this generated schema into the existing `config/300-repositories.yaml` CRD file.
3. Update the `Makefile` to include a new target, `update-schemas`, which executes the schema generation script.
4. Integrate a new job (`check-generated-schemas`) into the CI pipeline (`.tekton/linter.yaml`). This job will run `make update-schemas` and verify that no changes were made to the CRD file, ensuring that the committed schema is always up-to-date with the Go types.
5. Create comprehensive user documentation (`docs/content/docs/guide/openapi-schema.md`) explaining the benefits of OpenAPI schema validation, how to leverage it with tools like VS Code and `kubectl`, and how to troubleshoot validation errors.
6. Include `+kubebuilder:printcolumn` markers in the Go types to improve the default output columns when running `kubectl get repository`.

Dependencies

Describes what this story depends on. Dependent Stories and EPICs should be linked to the story.

• External tools: `controller-gen` (used for schema generation), `yq` (used by the generation script to merge schema).
• Go programming language and related Kubernetes libraries.

Acceptance Criteria (Mandatory)

Describe edge cases to consider when implementing the story and defining tests

Provides a required and minimum list of acceptance tests for this story. More is expected as the engineer implements this story

• The `Repository` CRD file (`config/300-repositories.yaml`) contains a well-defined `openAPIV3Schema` under `spec.versions[0].schema`.
• The schema definition includes accurate types, descriptions, required fields, and validation rules (patterns, enums, minimums) corresponding to the `RepositorySpec` and its nested structures as defined in the Go types.
• Running `make update-schemas` successfully regenerates or updates the `openAPIV3Schema` section in the CRD file based on the Go types without manual intervention.
• The CI job `check-generated-schemas` successfully verifies that the committed CRD schema is synchronized with the schema generated from the Go types.
• Applying a Repository resource with invalid fields (e.g., wrong type, missing required field, invalid pattern) using `kubectl apply --validate=strict` results in a validation error reported by the Kubernetes API server.
• IDEs configured with Kubernetes/YAML extensions provide accurate autocompletion, hover documentation (field descriptions), and real-time validation for Repository resources based on the schema.
• The new documentation page in the guide (`docs/content/docs/guide/openapi-schema.md`) is clear, technically accurate, and provides useful information on utilizing schema validation.
• Running `kubectl get repository` displays the additional status columns (URL, Succeeded, Reason, StartTime, CompletionTime) defined in the `+kubebuilder:printcolumn` markers.

INVEST Checklist

Dependencies identified - Verified

Blockers noted and expected delivery timelines set - Verified (Completed work)

Design is implementable - Verified (Completed work)

Acceptance criteria agreed upon - Verified

Story estimated - Verified (Completed work)

Legend

Unknown

Verified

Unsatisfied

Done Checklist

• Code is completed, reviewed, documented and checked in - Verified
• Unit and integration test automation have been delivered and running cleanly in continuous integration/staging/canary environment - Verified (CI check added)
• Continuous Delivery pipeline(s) is able to proceed with new code included - Verified
• Customer facing documentation, API docs etc. are produced/updated, reviewed and published - Verified (Documentation added)
• Acceptance criteria are met - Verified