Skip to content

Commit fa87124

Browse files
committed
feat(ci): gate sizeable API changes behind API-owner review
Add a deterministic api-gate tool (cmd/api-gate, internal/apigate) and a workflow that require an approving review from an API owner (lllamnyp or kvaps) when a PR introduces a new API group, a new resource, or a breaking schema change to an existing resource. Detection diffs the checked-in OpenAPIv3 schemas (apps cozyrds + CRD manifests) and the apiserver storage registrations; no network or LLM calls. Assisted-By: Claude <[email protected]> Signed-off-by: Timofei Larkin <[email protected]>
1 parent b25a132 commit fa87124

11 files changed

Lines changed: 1556 additions & 0 deletions

File tree

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
name: API Review Gate
2+
3+
# Requires a review from a designated API owner (see API_OWNERS below) when a
4+
# pull request makes a "sizeable" change to the Cozystack API surface: a new
5+
# API group, a new resource, or a breaking change to an existing resource's
6+
# schema. Detection is deterministic (cmd/api-gate); no LLM or network calls.
7+
#
8+
# The job runs on every PR (no path filter) so it can always report a status
9+
# and therefore be marked as a required check in branch protection without
10+
# leaving PRs that touch no API stuck in "pending". When nothing sizeable
11+
# changed it passes immediately.
12+
13+
on:
14+
pull_request:
15+
types: [opened, synchronize, reopened]
16+
# Re-evaluate when a review is submitted or dismissed so an approval by an
17+
# API owner flips the check from failing to passing without a new push.
18+
pull_request_review:
19+
types: [submitted, dismissed]
20+
21+
concurrency:
22+
group: api-review-gate-${{ github.event.pull_request.number }}
23+
cancel-in-progress: true
24+
25+
permissions:
26+
contents: read
27+
pull-requests: read
28+
29+
jobs:
30+
api-review-gate:
31+
name: Require API owner review for sizeable API changes
32+
runs-on: ubuntu-22.04
33+
env:
34+
# Space-separated GitHub logins allowed to satisfy the gate. Edit here to
35+
# change who can approve sizeable API changes.
36+
API_OWNERS: "lllamnyp kvaps"
37+
BASE_SHA: ${{ github.event.pull_request.base.sha }}
38+
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
39+
PR_NUMBER: ${{ github.event.pull_request.number }}
40+
GH_TOKEN: ${{ github.token }}
41+
steps:
42+
- name: Checkout head
43+
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
44+
with:
45+
ref: ${{ github.event.pull_request.head.sha }}
46+
fetch-depth: 0
47+
48+
- name: Set up Go
49+
uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
50+
with:
51+
go-version-file: go.mod
52+
cache: true
53+
54+
- name: Materialize base checkout
55+
run: |
56+
set -euo pipefail
57+
git worktree add --detach "${RUNNER_TEMP}/base" "${BASE_SHA}"
58+
59+
- name: Build api-gate
60+
run: go build -o "${RUNNER_TEMP}/api-gate" ./cmd/api-gate
61+
62+
- name: Detect sizeable API changes
63+
id: detect
64+
run: |
65+
set -uo pipefail
66+
set +e
67+
"${RUNNER_TEMP}/api-gate" \
68+
--base "${RUNNER_TEMP}/base" \
69+
--head "${GITHUB_WORKSPACE}" \
70+
--format markdown > "${RUNNER_TEMP}/report.md"
71+
code=$?
72+
set -e
73+
echo "code=${code}" >> "$GITHUB_OUTPUT"
74+
cat "${RUNNER_TEMP}/report.md"
75+
case "${code}" in
76+
0) echo "sizeable=false" >> "$GITHUB_OUTPUT" ;;
77+
2) echo "sizeable=true" >> "$GITHUB_OUTPUT" ;;
78+
*) echo "::error::api-gate failed with exit code ${code}"; exit "${code}" ;;
79+
esac
80+
81+
- name: Check for an API owner approval
82+
if: steps.detect.outputs.sizeable == 'true'
83+
run: |
84+
set -euo pipefail
85+
{
86+
echo "## API Review Gate"
87+
echo
88+
cat "${RUNNER_TEMP}/report.md"
89+
} >> "$GITHUB_STEP_SUMMARY"
90+
91+
# Latest review state per reviewer; an APPROVED review by any API
92+
# owner satisfies the gate. GitHub forbids self-approval, so a
93+
# sizeable PR authored by an owner still needs the other owner.
94+
approvals="$(gh api \
95+
"repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews" \
96+
--paginate \
97+
--jq '[.[] | select(.state=="APPROVED") | .user.login] | unique | .[]')"
98+
99+
for owner in ${API_OWNERS}; do
100+
if grep -qxi "${owner}" <<<"${approvals}"; then
101+
echo "Sizeable API change approved by @${owner}."
102+
exit 0
103+
fi
104+
done
105+
106+
echo "::error::This PR makes a sizeable API change (new group, new resource, or breaking change) and needs an approving review from one of: ${API_OWNERS}. See the job summary for details."
107+
exit 1

‎cmd/api-gate/main.go‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
/*
2+
Copyright 2026 The Cozystack Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
// Command api-gate compares the Cozystack API surface between two checkouts of
18+
// the repository and reports whether the change is "sizeable" — a new API
19+
// group, a new resource, or a breaking change to an existing resource. CI uses
20+
// a sizeable verdict to require a review from a designated API owner.
21+
//
22+
// Usage:
23+
//
24+
// api-gate --base <dir> --head <dir>
25+
//
26+
// Both flags point at a full repository checkout (the merge base and the PR
27+
// head). Exit code 0 means "not sizeable"; exit code 2 means "sizeable"
28+
// (findings are printed to stdout as a Markdown report); any other non-zero
29+
// exit is an operational error.
30+
package main
31+
32+
import (
33+
"flag"
34+
"fmt"
35+
"os"
36+
37+
"github.com/cozystack/cozystack/internal/apigate"
38+
)
39+
40+
// exitSizeable is a distinct, non-error exit code so the calling workflow can
41+
// tell "sizeable change, needs owner review" apart from a tool malfunction.
42+
const exitSizeable = 2
43+
44+
func main() {
45+
baseDir := flag.String("base", "", "path to the base (merge-base) repository checkout")
46+
headDir := flag.String("head", "", "path to the head (PR) repository checkout")
47+
format := flag.String("format", "markdown", "report format: markdown or text")
48+
flag.Parse()
49+
50+
if *baseDir == "" || *headDir == "" {
51+
fmt.Fprintln(os.Stderr, "api-gate: both --base and --head are required")
52+
flag.Usage()
53+
os.Exit(1)
54+
}
55+
56+
base, err := apigate.LoadSnapshot(*baseDir)
57+
if err != nil {
58+
fmt.Fprintf(os.Stderr, "api-gate: loading base snapshot: %v\n", err)
59+
os.Exit(1)
60+
}
61+
head, err := apigate.LoadSnapshot(*headDir)
62+
if err != nil {
63+
fmt.Fprintf(os.Stderr, "api-gate: loading head snapshot: %v\n", err)
64+
os.Exit(1)
65+
}
66+
67+
findings := apigate.Classify(base, head)
68+
if len(findings) == 0 {
69+
fmt.Println("No sizeable API changes detected.")
70+
return
71+
}
72+
73+
fmt.Print(apigate.Report(findings, *format))
74+
os.Exit(exitSizeable)
75+
}

‎internal/apigate/classify.go‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
/*
2+
Copyright 2026 The Cozystack Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package apigate
18+
19+
import (
20+
"fmt"
21+
"sort"
22+
)
23+
24+
// Classify compares the base and head snapshots and returns every sizeable
25+
// change, ordered deterministically (new groups, then new resources, then
26+
// breaking changes; each block sorted by group/plural/detail). An empty slice
27+
// means the change set is not sizeable and needs no designated-owner review.
28+
func Classify(base, head Snapshot) []Finding {
29+
var findings []Finding
30+
31+
baseGroups := base.groups()
32+
// New API groups: present in head, absent in base. Reported once per group
33+
// against the first (sorted) resource that introduces it.
34+
newGroups := map[string]struct{}{}
35+
for _, res := range sortedResources(head) {
36+
if _, ok := baseGroups[res.Group]; ok {
37+
continue
38+
}
39+
if _, done := newGroups[res.Group]; done {
40+
continue
41+
}
42+
newGroups[res.Group] = struct{}{}
43+
findings = append(findings, Finding{
44+
Category: NewGroup,
45+
Group: res.Group,
46+
Kind: res.Kind,
47+
Plural: res.Plural,
48+
Source: res.Source,
49+
Origin: res.Origin,
50+
Detail: fmt.Sprintf("API group %q is introduced by this change", res.Group),
51+
})
52+
}
53+
54+
// New resources: (group, plural) present in head, absent in base. A
55+
// resource whose group is itself new is already covered by the new-group
56+
// finding, so skip it here to avoid double-flagging.
57+
for _, res := range sortedResources(head) {
58+
if _, ok := base[res.key()]; ok {
59+
continue
60+
}
61+
if _, groupIsNew := newGroups[res.Group]; groupIsNew {
62+
continue
63+
}
64+
findings = append(findings, Finding{
65+
Category: NewResource,
66+
Group: res.Group,
67+
Kind: res.Kind,
68+
Plural: res.Plural,
69+
Source: res.Source,
70+
Origin: res.Origin,
71+
Detail: fmt.Sprintf("resource %s (%s) is added to group %q", res.Plural, displayKind(res), res.Group),
72+
})
73+
}
74+
75+
// Breaking changes: resources present in both, whose schema regresses.
76+
for _, res := range sortedResources(head) {
77+
prev, ok := base[res.key()]
78+
if !ok {
79+
continue
80+
}
81+
for _, detail := range diffResource(prev, res) {
82+
findings = append(findings, Finding{
83+
Category: Breaking,
84+
Group: res.Group,
85+
Kind: res.Kind,
86+
Plural: res.Plural,
87+
Source: res.Source,
88+
Origin: res.Origin,
89+
Detail: detail,
90+
})
91+
}
92+
}
93+
94+
return findings
95+
}
96+
97+
// diffResource returns human-readable descriptions of every breaking change
98+
// between the base and head form of one resource: a removed served version, or
99+
// a breaking schema change within a shared version. New versions are additive
100+
// and ignored.
101+
func diffResource(base, head Resource) []string {
102+
var out []string
103+
versions := make([]string, 0, len(base.Versions))
104+
for v := range base.Versions {
105+
versions = append(versions, v)
106+
}
107+
sort.Strings(versions)
108+
for _, v := range versions {
109+
headSchema, ok := head.Versions[v]
110+
if !ok {
111+
out = append(out, fmt.Sprintf("served version %q was removed", v))
112+
continue
113+
}
114+
for _, c := range diffSchema("spec", base.Versions[v], headSchema) {
115+
out = append(out, fmt.Sprintf("[%s] %s", v, c))
116+
}
117+
}
118+
return out
119+
}
120+
121+
func displayKind(r Resource) string {
122+
if r.Kind != "" {
123+
return r.Kind
124+
}
125+
return r.Plural
126+
}
127+
128+
// sortedResources returns a snapshot's resources in a stable order for
129+
// deterministic output.
130+
func sortedResources(s Snapshot) []Resource {
131+
out := make([]Resource, 0, len(s))
132+
for _, r := range s {
133+
out = append(out, r)
134+
}
135+
sort.Slice(out, func(i, j int) bool {
136+
if out[i].Group != out[j].Group {
137+
return out[i].Group < out[j].Group
138+
}
139+
return out[i].Plural < out[j].Plural
140+
})
141+
return out
142+
}

0 commit comments

Comments
 (0)