ci: refresh the committed Weaviate OpenAPI spec automatically - #518
Merged
Conversation
static/specs/weaviate-openapi.json is a committed copy of a file that lives in weaviate/weaviate. Nothing in this repo notices when it falls behind, because a stale-but-valid spec looks exactly like a fresh one — so the site can keep publishing an old API contract indefinitely, and the only thing preventing that is someone remembering. Add a weekly job that resolves the newest v*/openapi-for-docs branch upstream, downloads openapi-specs/schema.json, and opens a PR only when the bytes differ, with the info.version and path-count delta in the body so the change is legible without diffing 11,000 lines. Branch selection sorts on (major, minor) numerically, because v1-9 sorts above v1-10 lexically. The download is validated as a Swagger document with a non-empty paths object before anything is written, so a rate-limit page cannot be committed over the spec. It uses the built-in GITHUB_TOKEN rather than a PAT: a PAT is one more secret to rotate, and an expired one has already broken a version-fetch job in this repo. That trade needs "Allow GitHub Actions to create and approve pull requests" enabled for the repository, or the final step fails with a 403. Merge this after the PR that adds static/specs/weaviate-openapi.json — the job reads that file to compute the delta, and fails if it is not there yet.
![orca-security-eu[bot]](https://avatars.githubusercontent.com/in/276244?s=60&v=4){kind=small}
There was a problem hiding this comment.
Orca Security Scan Summary
| Status | Check | Issues by priority | |
|---|---|---|---|
 Passed |
Infrastructure as Code |  0  0  0  0 |
View in Orca |
| Passed |
SAST | 0 0 0 0 |
View in Orca |
| Passed |
Secrets | 0 0 0 0 |
View in Orca |
| Passed |
Vulnerabilities | 0 0 0 0 |
View in Orca |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Keeps
static/specs/weaviate-openapi.jsoncurrent without anyone remembering to. Weekly (Sunday 21:00 UTC, offset from the existing scheduled jobs), it resolves the newestv*/openapi-for-docsbranch in weaviate/weaviate, downloadsopenapi-specs/schema.json, and opens a PR only when the bytes differ — with theinfo.versionand path-count delta in the body, so the change is reviewable without diffing 11,000 lines. Weekly because upstream only moves when core cuts a release branch, roughly every 6-8 weeks.Two things a reviewer cannot see in the diff:
GITHUB_TOKENrather than a PAT — one less secret to rotate, and an expired PAT has already broken a version-fetch job here — but without that setting the final step fails with a 403. Nothing in this repo opens PRs from CI today, so assume it is off until checked.GITHUB_TOKENdoes not trigger other workflows. The PR this job opens will arrive with no build or link checks having run. Close and reopen it to run them before merging. The PR body says so too.Merge after the PR that adds
static/specs/weaviate-openapi.json— this job reads that file to compute the delta and fails if it is not there.Verified locally: both paths dry-run against the live GitHub API (no-op when identical; correct
1.38.0-rc.0/73 →1.39.0/77 delta when not), YAML parses, allrunblocks passbash -nandshellcheck. The version sort is numeric on (major, minor), sincev1-9sorts abovev1-10lexically. The scheduled run itself cannot be exercised before merge —scheduleandworkflow_dispatchonly fire from the default branch.