docs: automate API reference regeneration (CI + RDE, nightly + manual)#80
Merged
Conversation
Adds a scheduled + manual workflow that keeps the generated RDE API reference in sync with the hosted OpenAPI spec, and unifies the spec-change detection shared with the CI API spec. - api/bitrise-rde.json: committed snapshot of the RDE spec; docusaurus.config.ts now generates from it instead of the live URL. - .github/workflows/sync-rde-api.yml: nightly (06:00 UTC) + workflow_dispatch. On a detected change it regenerates the reference and opens a PR (never commits to main). Uses RDE_SYNC_TOKEN when present so the PR triggers checks; falls back to GITHUB_TOKEN. - scripts/spec_sync.py: shared change detector — ETag conditional GET (304 when unchanged) plus a SHA-256 content gate as the source of truth, which handles the CI host's mtime-based ETag and the RDE host's content ETag alike. 30s fetch timeout. - scripts/sync_api_spec.py, scripts/sync_rde_spec.py: thin wrappers over it. - scripts/*_sync_state.json: ETag + content-hash baselines. - .gitignore: ignore scripts/__pycache__/. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
gaborszakacs
requested review from
aorcsik,
ilanazholobovsky,
matenadasdi and
zoltan-baba
as code owners
Generalize the nightly/manual sync workflow to handle the Bitrise CI API spec as well as RDE. Each spec runs as its own matrix job — its own PR branch (auto/ci-api-sync, auto/rde-api-sync), independent of the other — so the two products stay separate for review and don't block each other on a flaky host. Renames the workflow to sync-api-references.yml and the optional PAT secret to DOCS_SYNC_TOKEN (it now covers all docs API syncs). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
gaborszakacs
force-pushed
the
docs/rde-api-autosync
branch
from
dbaf253 to
d13b2de
Compare
gaborszakacs
changed the title
# Conflicts: # scripts/api_spec_sync_state.json
matenadasdi
approved these changes
Jun 29, 2026
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
3 participants
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.
Summary
Keeps the generated API references in sync with their hosted OpenAPI specs, with no manual work. A scheduled + manually-triggerable GitHub Action detects when a spec changes, regenerates that reference, and opens a PR for review (it never commits to
main).Covers both the Bitrise CI API and the RDE API. Follow-up to #77 (merged), which generated the RDE reference natively.
How it's structured
One workflow file, matrixed over the two specs — each spec runs as its own job and opens its own PR (
auto/ci-api-sync,auto/rde-api-sync). That keeps the two products independent (separate review/ownership, independent runs) while staying DRY; a third spec later is a one-line matrix entry.What's included
api/bitrise-rde.json— committed RDE spec snapshot.docusaurus.config.tsnow generates the RDE reference from the snapshot instead of the live URL (the CI reference already worked this way)..github/workflows/sync-api-references.yml—schedule(nightly, 06:00 UTC) +workflow_dispatch. Per spec: detect change →gen-api-docs <spec>→ open/update a PR viapeter-evans/create-pull-request, scoped to that spec's files.scripts/spec_sync.py— shared change detector for both specs:If-None-Match→304) to skip unchanged downloads, plusmtime-size), so the hash is what decides "changed" — protecting against nginx ETag churn on redeploys and the no-ETag window. 30s fetch timeout.scripts/sync_api_spec.py/scripts/sync_rde_spec.py— thin wrappers over the shared module.scripts/*_sync_state.json— ETag + content-hash baselines (CI backfilled for a seamless migration)..gitignore— ignorescripts/__pycache__/.Setup note
For the bot's PRs to trigger the deploy preview + checks, add a PAT/App token as repo secret
DOCS_SYNC_TOKEN. Without it the workflow falls back toGITHUB_TOKEN(PRs still open, butGITHUB_TOKEN-authored PRs don't trigger other workflows). Triggers activate once this is onmain.Verification
Both syncs run against their live hosts: CI →
304/unchanged(api/bitrise-ci.jsonuntouched), RDE →200→ SHA-matchedunchanged(snapshot untouched; ETag captured). Thechanged,--update, and corrupted-hash paths were exercised; scripts compile; workflow YAML + matrix validate.Pairs with bitrise-io/bitrise-codespaces#217, which makes the RDE host send the content ETag (now live).
🤖 Generated with Claude Code