New SIG Proposal: API Review

[Adam Kaplan]

Today, Konflux components spread out their custom resource definitions in individual repositories, keeping their APIs alongside the respective controller code. While this allows for faster iteration within a controller, it makes coordination across components harder. Breaking changes (like the recent one in the Component object) can sneak by because maintaining Kubernetes APIs requires a high level of expertise [1]. Separate repositories also makes qualitative user experience assessments harder to comprehend.

I propose all new Konflux APIs - like the new ComponentGroup model - be consolidated into a single API repository. This repository will be maintained by a dedicated SIG group (“API Review”) responsible for enforcing API standards and stewarding the user experience of Konflux custom resource definitions. This group will also mediate design discussions within new or updated custom resource definitions, which is often a point of contention in our current ADR process. With this SIG in place, ADRs will not need to provide an exact API specification to be approved.

Thoughts on this?

[1] 

https://github.com/konflux-ci/application-api/pull/93

Adam Kaplan

He/Him

Senior Principal Software Engineer

Red Hat

100 E. Davie Street

adam....@redhat.com    

[Martin Basti]

We had single API repo before, and we were slowly moving to isolated APIs, as so far, konflux services should be able to work/develop independently. It was pain to synchronize controllers and API between separate repos. I'm against this.

If the changes to needs extra check, then we can make this API Review SIG codeowners of API files in each component.

--
You received this message because you are subscribed to the Google Groups "Konflux CI" group.
To unsubscribe from this group and stop receiving emails from it, send an email to konflux+u...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/konflux/CADmLb%2B%3D6qW_TJg%2Bo2T-Rx7vh5xCOuAkN7X9MgdZOMtgdM1TzkQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[Srushti Kaware]

Dear Adam and Martin,

Thank you both for sharing your perspectives on this.

Adam’s proposal for a centralized API repository seems valuable from a consistency and user-experience standpoint, especially when it comes to maintaining standards for Kubernetes custom resource definitions and preventing breaking changes.

At the same time, Martin’s point about the operational difficulty of synchronizing controllers and APIs across repositories is also important, particularly if the goal is to allow Konflux services to evolve independently.

Perhaps a middle ground could be to keep APIs within their respective component repositories while establishing the proposed API Review SIG as code owners for API-related files. This might help maintain consistency and review quality without introducing the synchronization challenges of a single repository.

I appreciate the discussion and look forward to learning more from the community as this evolves.

Best regards,

Srushti Kaware

To view this discussion visit https://groups.google.com/d/msgid/konflux/5e55b880-2ae6-4e65-9a56-b4bc629f23ba%40redhat.com.

[Martin Basti]

On 7. 3. 2026 5:12, Srushti Kaware wrote:

Dear Adam and Martin,

Thank you both for sharing your perspectives on this.

Adam’s proposal for a centralized API repository seems valuable from a consistency and user-experience standpoint, especially when it comes to maintaining standards for Kubernetes custom resource definitions and preventing breaking changes.

At the same time, Martin’s point about the operational difficulty of synchronizing controllers and APIs across repositories is also important, particularly if the goal is to allow Konflux services to evolve independently.

Perhaps a middle ground could be to keep APIs within their respective component repositories while establishing the proposed API Review SIG as code owners for API-related files. This might help maintain consistency and review quality without introducing the synchronization challenges of a single repository.

That's basically what I proposed. I'm glad we are on the same page

[Gal Ben Haim]

On Fri, Mar 6, 2026 at 12:16 PM 'Martin Basti' via Konflux CI <kon...@googlegroups.com> wrote:

We had single API repo before, and we were slowly moving to isolated APIs, as so far, konflux services should be able to work/develop independently. It was pain to synchronize controllers and API between separate repos. I'm against this.

If the changes to needs extra check, then we can make this API Review SIG codeowners of API files in each component.

+1 

On 5. 3. 2026 13:49, 'Adam Kaplan' via Konflux CI wrote:

Today, Konflux components spread out their custom resource definitions in individual repositories, keeping their APIs alongside the respective controller code. While this allows for faster iteration within a controller, it makes coordination across components harder. Breaking changes (like the recent one in the Component object) can sneak by because maintaining Kubernetes APIs requires a high level of expertise [1]. Separate repositories also makes qualitative user experience assessments harder to comprehend.

I propose all new Konflux APIs - like the new ComponentGroup model - be consolidated into a single API repository. This repository will be maintained by a dedicated SIG group (“API Review”) responsible for enforcing API standards and stewarding the user experience of Konflux custom resource definitions. This group will also mediate design discussions within new or updated custom resource definitions, which is often a point of contention in our current ADR process. With this SIG in place, ADRs will not need to provide an exact API specification to be approved.

Thoughts on this?

[1] 

https://github.com/konflux-ci/application-api/pull/93

Adam Kaplan

He/Him

Senior Principal Software Engineer

Red Hat

100 E. Davie Street

adam....@redhat.com    

--
You received this message because you are subscribed to the Google Groups "Konflux CI" group.
To unsubscribe from this group and stop receiving emails from it, send an email to konflux+u...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/konflux/CADmLb%2B%3D6qW_TJg%2Bo2T-Rx7vh5xCOuAkN7X9MgdZOMtgdM1TzkQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Konflux CI" group.
To unsubscribe from this group and stop receiving emails from it, send an email to konflux+u...@googlegroups.com.

To view this discussion visit https://groups.google.com/d/msgid/konflux/5e55b880-2ae6-4e65-9a56-b4bc629f23ba%40redhat.com.

For more options, visit https://groups.google.com/d/optout.

--

GAL bEN HAIM

KoNFLUX ARCHITECTURE

[Adam Kaplan]

It's settled then - we have consensus around no central repository (lesson learned from the past) and declaring this group as OWNERS in code repositories. This feels pretty easy to pull off since most go-based projects have dedicated directories for CRD definitions.

We can also document our API standards so that reviewers and agents use the same evaluation rubrics. The Kubernetes API conventions are a good place to start [1].

[1] https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md

To view this discussion visit https://groups.google.com/d/msgid/konflux/CADpdQO6MUa%2BBPRvOBkLBBHrrgAwuw8ttiWukaQ3We3uX6T7N9A%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--