Skip to content

PLAT-1314/ci: reject stale embedded OpenAPI specs #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brtkwr merged 1 commit into from
Oct 29, 2026
Merged

PLAT-1314/ci: reject stale embedded OpenAPI specs #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ jobs:
go-version: '1.26'
cache: true
- run: go build ./...
- name: Check embedded spec drift
run: make check-generated
- run: make test-cover

lint:
Expand Down
5 changes: 4 additions & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.PHONY: build install regen test test-cover lint tidy clean release-dry help
.PHONY: build install regen check-generated test test-cover lint tidy clean release-dry help

BINARY := twoctl
PKG := github.com/two-inc/twoctl-cli
Expand All @@ -17,6 +17,9 @@ install: ## Install twoctl into $$GOBIN (or $$GOPATH/bin).
regen: ## Refresh embedded OpenAPI specs from openapi/<api>-api.yaml.
./scripts/codegen.sh

check-generated: ## Regenerate embedded specs and fail if committed output is stale.
./scripts/check-generated.sh

test: ## Run all unit tests.
go test ./...

Expand Down
8 changes: 8 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -261,6 +261,14 @@ To regenerate locally:
go build ./...
```

CI runs `make check-generated` on every pull request and main-branch push.
It regenerates the embedded specs from the committed `openapi/` inputs and
fails if any embedded file changes or is newly generated but untracked.
When changing source specs or the preprocessor, run `make regen` and commit
the updated `cmd/twoctl/cli/specs/` files with the change. This check uses
vendored inputs and does not fetch upstream specs or require API credentials;
the nightly `regenerate` workflow continues to handle upstream refreshes.

## Contributing

This repository is generated from the OpenAPI specs in [`two-inc/docs`](https://github.com/two-inc/docs).
Expand Down
20 changes: 20 additions & 0 deletions scripts/check-generated.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
#!/usr/bin/env bash
# Check that the embedded OpenAPI specs match their committed source inputs.
set -euo pipefail

ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "${ROOT}"

./scripts/codegen.sh

# Include untracked files: adding a generator output must fail until that new
# file is committed, even though git diff alone would not show it.
changes="$(git status --porcelain --untracked-files=all -- cmd/twoctl/cli/specs/)"

@chatgpt-codex-connector chatgpt-codex-connector Bot Oct 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Remove orphaned outputs before checking drift

When an API is removed or renamed in scripts/codegen.sh, regeneration leaves its previously tracked .processed.yaml file untouched, and this status check therefore reports a clean tree. Because operations.go embeds every matching file—and can still reference the orphan through its separate apiMeta list—a support-removal change can pass this gate while retaining and potentially exposing the stale API. Clear the generated directory before regeneration or compare its complete file set against the expected outputs.

Useful? React with 👍 / 👎.

if [[ -n "${changes}" ]]; then
echo "::error::Embedded OpenAPI specs are stale. Run make regen and commit cmd/twoctl/cli/specs/."
printf '%s\n' "${changes}"
git --no-pager diff -- cmd/twoctl/cli/specs/
exit 1
fi

echo "embedded OpenAPI specs are up to date"
Loading