feat(api): automate Cloud and OSS v2 spec sync

[jstirnaman]

Closes # — none. Related: #7666, #7667, #7668, influxdata/openapi#655, and influxdata/influxdb#27585.

What changed

Adds two independent scheduled sync workflows:

Product	Schedule	OpenAPI contract	Generated PR branch
Cloud v2	Monday at 06:30 UTC	contracts/ref/cloud.yml	sync/openapi-cloud-v2-spec
OSS v2	Monday at 07:00 UTC	contracts/ref/oss.yml	sync/openapi-oss-v2-spec

Each workflow:

• supports manual dispatch;
• resolves the current influxdata/openapi/master commit;
• regenerates from that exact SHA rather than a moving branch URL;
• records the SHA in the generated PR;
• applies the appropriate source:sync and product labels;
• recommends conditional waiting and release labels;
• recommends the implementation and release records to link; and
• opens or updates its own PR only when its generated spec changes.

Clean regeneration (resolves #7668)

Moves OSS v2 and Cloud v2 to a raw-mirror pipeline so a scheduled sync diffs
cleanly against influxdata/openapi instead of mixing upstream changes with
decorator churn:

• Adds a docs/mirror redocly config (api-docs/openapi/plugins/docs-plugin.cjs)
  with no decorators, used only by influxdb/v2/.config.yml and
  influxdb/cloud/.config.yml. getswagger.sh now commits these two specs as
  a plain upstream bundle — $ref-resolved, unmodified otherwise. Every other
  product keeps docs/all and decorates at commit time as before.
• Ports the five retired decorators (delete-servers, remove-private-paths,
  strip-version-prefix, strip-trailing-slash, replace-docs-url-shortcode) into
  api-docs/scripts/post-process-specs.ts as plain TypeScript, gated to
  MIRROR_PRODUCT_PATHS, applied at build time into the gitignored _build/
  that generate-openapi-articles.ts already reads exclusively — so published
  output is unaffected in kind.
• Fixes the doc-link rewrite along the way: it now walks every string in the
  spec, not just description fields, so externalDocs.url gets corrected
  too. The committed OSS v2 spec carried 229 /influxdb/latest/ links that
  should read /influxdb/v2/ — a one-time hand patch from years ago
  (4403dd9a1) that every regen silently reverted because no transform
  reproduced it. This re-baseline regen fixes all of them as a repeatable
  transform instead.
• Re-baselines both committed specs against the new pipeline in this PR, so
  the first scheduled sync after merge is a real, small diff — not another
  wholesale rewrite.

Why

Cloud v2 and OSS v2 ship independently.
A combined generated PR could mix API changes with different release timing and
prevent reviewers from merging one product safely.

Releases are infrequent enough that separate weekly docs-v2 checks provide a
simpler solution than cross-repository release integration.
The generated PRs preserve the docs-v2 human approval gate.

The onConflict change shows why this gate is necessary:
influxdata/openapi#655 merged on August 8, 2026, but the corresponding server
implementation in influxdata/influxdb#27585 remains an open draft against
main-2.x.
A merged OpenAPI change is therefore a change proposal, not evidence that the
behavior is implemented or released.

The OSS workflow uses the current OpenAPI master contract as a change
proposal instead of relying on the manually maintained
docs-release/influxdb-oss branch.
Its PR instructs reviewers to verify that every API change has shipped before
merge and to regenerate from an exact tag or commit if only part of the proposed
contract is released.

Baking decorators into the committed spec meant every regen diff mixed real
influxdata/openapi changes with decorator output, defeating clean review —
the exact problem #7668 reported. Moving decorators to build time makes the
commit a pristine mirror, so a scheduled sync PR shows reviewers only what
actually changed upstream.

Impact

The workflows update only these generated files:

• api-docs/influxdb/cloud/influxdb-cloud-v2-openapi.yaml
• api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml

This PR's own commit already re-baselines both files against the new
pipeline, so reviewers should expect a large diff here once, converting the
committed specs from decorated output to a raw upstream mirror. After merge,
each scheduled sync PR should be a small, real diff.
Reviewers must confirm that each API change is available in the corresponding
product before merging.

Only influxdb/v2 and influxdb/cloud are affected by the pipeline change.
Other products (influxdb3/*, influxdb/v1, enterprise_influxdb/v1) keep
docs/all and decorate at commit time, unchanged.

The scheduled workflows do not run until they reach the default branch.

Verification

• Parsed both workflow files successfully as YAML.
• Verified that each workflow resolves and records an exact OpenAPI SHA.
• Verified that the generated OSS PR distinguishes a merged OpenAPI change from
  an implemented and released server change.
• Verified recommended labels against data/labels.yml and product labels
  against data/products.yml.
• Verified that both generated PR templates identify the engineering and release
  records reviewers should link.
• Verified that each workflow passes the SHA-based raw URL to
  getswagger.sh -b.
• Verified that each workflow has one fixed PR branch and one
  create-pull-request step.
• Verified the workflows use valid getswagger.sh product names:
  cloud-v2 and v2.
• Compared the pinned action SHAs with
  .github/workflows/sync-client-library-release-notes.yml.
• Did not run the workflows in GitHub Actions because scheduled and manual
  workflows run from the default branch.
• tsc -p api-docs/scripts/tsconfig.json compiles clean.
• node api-docs/scripts/dist/test-post-process-specs.js: 52/52 passing,
  including 2 new tests for the ported mirror transforms and for non-mirror
  products being unaffected.
• Regenerated both specs via getswagger.sh v2 / cloud-v2: committed
  source now carries raw docs.influxdata.com links, confirming it mirrors
  upstream instead of decorated output.
• Ran post-process-specs.js for both products: _build/ output has zero
  /influxdb/latest/ links remaining (was 229 for OSS v2, 5 for Cloud v2).
• Ran generate-openapi-articles.js --skip-fetch oss-v2 cloud-v2 end to end:
  succeeded, all generated output lands in gitignored paths.
• Ran yarn build:api-docs and yarn hugo serve. Visually inspected /static files using jq.

Checklist

• Signed the InfluxData CLA (if necessary)
• Rebased/mergeable
• Local build passes (npx hugo --quiet) — not applicable; no site files changed (all generated content lands in gitignored paths)

[jstirnaman]

CI status on 1c4b2dd: block-ephemeral-docs failed; everything else passed or skipped. (job)

That failure is the workflow doing its job, not a defect. .github/workflows/block-ephemeral-docs.yml fails whenever PLAN.md or HANDOVER.md exists on a PR targeting master, and PLAN.md is the only file this PR adds. It will stay red for as long as the plan lives here.

I'm not pushing a fix, because the only fix is deleting the PR's entire contents — a call for a maintainer, not something to do automatically. Two ways forward:

1. Leave it as a draft until influxdata/openapi#655 merges, then replace PLAN.md with the regenerated spec in the same PR. The check goes green when the plan file goes away.
2. Close this PR and move the contents somewhere durable — API reference: upstream INFLUXDB_DOCS_URL substitution pins v2 links to /influxdb/latest and emits broken URLs #7666, api-docs: tags.yml links to a QuerystringAuthentication anchor that no longer exists in the v2 and Cloud specs #7667, and api-docs: committed OpenAPI specs are stale artifacts of the old pipeline — re-baseline before the next spec update #7668 already carry the three findings, so the unique value left in PLAN.md is the regeneration runbook and the release-timing constraint.

I'd lean toward 1, since the branch and runbook are only useful until #655 lands. Happy to do either.

---

Generated by Claude Code

[jstirnaman]

⚠️ The SHA-pinning commits change which branch the OSS spec comes from, and that just became load-bearing — influxdata/openapi#655 merged to master about an hour ago.

What changed

sync-openapi-oss-v2-spec.yml resolves refs/heads/master:

git ls-remote --exit-code https://github.com/influxdata/openapi.git refs/heads/master

then passes it as -b. In api-docs/getswagger.sh, -b sets both base URLs (line 87):

b)
  baseUrl=$OPTARG
  baseUrlOSS=$OPTARG
  ;;

and the v2 target reads $baseUrlOSS (line 277). So getswagger.sh v2 -b <master-sha-url> fetches contracts/ref/oss.yml from master, not from the docs-release/influxdb-oss default on line 24. Pinning to an immutable SHA is a clear improvement; the branch switch is the part worth confirming.

Why it matters right now

openapi master (d90ba20)	has onConflict — #655 merged
openapi docs-release/influxdb-oss	does not have it
influxdata/influxdb#27578 (server-side --on-conflict)	still open, no linked PR

The next OSS sync — Monday 07:00 UTC, or any workflow_dispatch — will therefore open a PR adding onConflict to the published OSS v2 reference, documenting a parameter that no released InfluxDB OSS server implements. The two contracts were byte-identical until #655 landed, so this wouldn't have shown up in testing before today.

This also drops the docs-release/influxdb-oss gate that api-docs/README.md ("InfluxDB OSS v2 version") documents as the reason OSS reference docs track a release branch rather than master.

Is this intended?

The commit message (refactor(api): sync OSS v2 from pinned master revision) reads deliberate, and the new PR body — "confirm that every API change is available in a released InfluxDB OSS v2 version… If only a subset has shipped, regenerate from the appropriate OpenAPI tag or commit instead" — is consistent with moving the gate from the branch to the reviewer. That's a coherent design; it just trades an automatic guarantee for reviewer discipline on every sync, and the first PR it produces will be one that shouldn't merge.

Two options:

1. Keep the branch gate. Resolve refs/heads/docs-release/influxdb-oss instead of refs/heads/master in the OSS workflow. Still SHA-pinned and immutable, still reproducible — the one-line change is the ref in git ls-remote. Cloud stays on master, which is correct for it.
2. Keep master as the source and accept the reviewer gate, but say so in api-docs/README.md so the README and the workflow don't disagree about where OSS specs come from.

I'd go with 1 — it keeps the invariant enforced by the pipeline rather than by whoever reviews the sync PR at 7am Monday. Happy to push either.

---

Generated by Claude Code

[Copilot]

Pull request overview

Adds independent weekly workflows to synchronize Cloud v2 and OSS v2 OpenAPI specifications while preserving human review gates.

Changes:

• Pins upstream contracts to resolved OpenAPI commit SHAs.
• Creates product-specific pull requests with review guidance and labels.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
.github/workflows/sync-openapi-oss-v2-spec.yml	Adds OSS v2 specification synchronization.
.github/workflows/sync-openapi-cloud-v2-spec.yml	Adds Cloud v2 specification synchronization.

Suppressed comments (4)

.github/workflows/sync-openapi-oss-v2-spec.yml:47

• Resolving the contract to an exact SHA does not make this generation reproducible: getswagger.sh:123-131 runs the unversioned npx @redocly/cli, so a new CLI release can rewrite or break the spec even when the OpenAPI SHA is unchanged. Issue #7668 already identifies this generator dependency as unpinned. Pin it in the API-docs dependencies/lockfile and have the script use that local version before scheduling automated syncs.

          bash getswagger.sh v2 \
            -b "https://raw.githubusercontent.com/influxdata/openapi/$OPENAPI_SHA"

.github/workflows/sync-openapi-oss-v2-spec.yml:50

• With no token input, this action uses GITHUB_TOKEN; the action documents that PRs created or updated with that token do not trigger push or pull_request workflows. Consequently the generated API-spec PR will not automatically run this repository's PR Preview (which includes api-docs/**) or the other PR validation jobs. Use a GitHub App/PAT token intended for automation, or explicitly dispatch the required checks after creating/updating the PR.

      - name: Create or update pull request
        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1  # v8

.github/workflows/sync-openapi-cloud-v2-spec.yml:47

• Resolving the contract to an exact SHA does not make this generation reproducible: getswagger.sh:123-131 runs the unversioned npx @redocly/cli, so a new CLI release can rewrite or break the spec even when the OpenAPI SHA is unchanged. Issue #7668 already identifies this generator dependency as unpinned. Pin it in the API-docs dependencies/lockfile and have the script use that local version before scheduling automated syncs.

          bash getswagger.sh cloud-v2 \
            -b "https://raw.githubusercontent.com/influxdata/openapi/$OPENAPI_SHA"

.github/workflows/sync-openapi-cloud-v2-spec.yml:50

• With no token input, this action uses GITHUB_TOKEN; the action documents that PRs created or updated with that token do not trigger push or pull_request workflows. Consequently the generated API-spec PR will not automatically run this repository's PR Preview (which includes api-docs/**) or the other PR validation jobs. Use a GitHub App/PAT token intended for automation, or explicitly dispatch the required checks after creating/updating the PR.

      - name: Create or update pull request
        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1  # v8

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jstirnaman]

Checked all three Copilot findings against the repo. All are technically correct, but two of them describe pre-existing repo-wide patterns rather than anything these workflows introduce — worth knowing before deciding where to fix them.

1. No CI on the generated sync PRs — the most consequential, and Copilot suppressed it

create-pull-request with GITHUB_TOKEN cannot trigger on: pull_request workflows. This repo has 12 of them:

auto-label, block-ephemeral-docs, doc-review, pr-feedback-links, pr-link-check, pr-lockfile-lint, pr-preview, pr-release-check, pr-remark-check, pr-render-check, pr-vale-check, test

So a weekly sync PR arrives with zero checks — no link check, no Vale, no render check, no preview — which is a real gap for a PR whose entire purpose is reviewing generated output.

Pre-existing, though: sync-plugins.yml (explicitly token: ${{ secrets.GITHUB_TOKEN }}), sync-client-library-release-notes.yml, and check-pinned-deps.yml all have the same limitation today. Fixing it needs an App token or PAT, so it's an infra decision, and arguably one to make once for all four workflows rather than only here.

2. persist-credentials — valid hardening, also the repo-wide default

Correct that actions/checkout leaves a write-scoped credential in .git/config, that npx @redocly/cli then executes an unpinned package in the same job, and that create-pull-request authenticates separately so it doesn't need that credential. persist-credentials: false is a safe one-line addition to both workflows.

Also pre-existing — none of the three sync workflows above set it. But the specific combination here (persisted write credential + unpinned remote code execution in the same job) is what makes it worth acting on, and that combination comes from finding 3.

3. Unpinned @redocly/cli — the root cause, and the highest-leverage fix

Copilot reached the same conclusion I did in #7668 independently. It's worth stating plainly that this one finding drives the other two:

• It's why SHA-pinning the contract doesn't actually make the sync reproducible — a Redocly release can rewrite the spec with the OpenAPI SHA unchanged, producing a sync PR that looks like an upstream change but isn't.
• It's what turns finding 2 from theoretical into concrete, since the untrusted code and the write credential share a job.

Pinning it in api-docs/package.json and calling the local binary from getswagger.sh addresses reproducibility and defuses most of finding 2. Caveat from #7668: the pinned version has to be chosen deliberately, because the committed specs were generated with a Redocly 1.x CLI and the current npx resolves 2.46.0 — so pinning and re-baselining should land together, before these schedules go live.

Suggested order

1. Pin @redocly/cli + re-baseline (api-docs: committed OpenAPI specs are stale artifacts of the old pipeline — re-baseline before the next spec update #7668) — unblocks everything else.
2. Add persist-credentials: false to both workflows (and ideally the other three sync workflows).
3. Decide separately, repo-wide, whether sync PRs should run CI via an App token.

Happy to take any of these. 1 and 2 are the ones I'd do first; 3 needs a secret I can't provision.

---

Generated by Claude Code

[jstirnaman]

Verified the pin commit (49d8669) in a clean worktree. It holds up, and it also lets me replace my earlier argument about the OSS source branch with an actual measurement.

Pin verification — all claims confirmed

Check	Result
yarn install --frozen-lockfile from clean node_modules	✅ succeeds (2.7s)
node_modules/.bin/redocly --version	✅ 2.47.0
bash getswagger.sh v2 reproduces the committed baseline	✅ zero diff — idempotent

I'd expected the lockfile entry to be incomplete, since it adds @redocly/cli@2.47.0 with no transitive dependencies. That was wrong — the package resolves standalone and --frozen-lockfile is satisfied. The guard in postProcess that errors with "Run 'yarn install' in api-docs first" is a nice touch; it fails loudly rather than silently falling back.

What the first OSS sync PR will actually contain

Same worktree, same pinned binary, only the source differs:

# defaults → docs-release/influxdb-oss
bash getswagger.sh v2
#   → 0 lines changed, no onConflict

# what the workflow runs → master @ d90ba20
bash getswagger.sh v2 -b "https://raw.githubusercontent.com/influxdata/openapi/d90ba20…"
#   → +9 lines, onConflict present

So the first sync PR is a clean 9-line diff adding onConflict to PostRestoreBucketMetadata — nothing else, now that the re-baseline has landed. That is a genuinely good outcome for a first automated run.

I'd flagged this earlier as a possible regression. Having now seen refactor(api): sync OSS v2 from pinned master revision alongside the "confirm that every API change is available in a released InfluxDB OSS v2 version… regenerate from the appropriate OpenAPI tag or commit instead" guidance and the new waiting:pr / release:pending labels, the design reads as deliberate: propose from master, gate at review. My measurement confirms it behaves that way rather than contradicting it. influxdata/influxdb#27578 is still open, so that first PR should land waiting:pr + release:pending and sit — exactly what the labels are for.

One thing left

api-docs/README.md ("InfluxDB OSS v2 version") still says OSS reference docs are generated from the docs-release/influxdb-oss branch, which is now only true for a local getswagger.sh v2 run, not for the automated sync. Worth a short update so the README and the workflow don't disagree — happy to push it if useful.

---

Generated by Claude Code

[jstirnaman]

Verified 7bd1659 by building _build/ at 49d8669 and at 7bd1659 in separate worktrees and diffing the results. One thing reviewers should know: this refactor is not output-neutral — it fixes 211 links.

Published output changes

Build	/influxdb/latest/ links in OSS v2	in Cloud v2
49d8669 (decorators at bundle time)	206	5
7bd1659 (decorators at build time)	0	0

applyMirrorTransforms rewrites https://docs.influxdata.com/influxdb/latest/ and bare /influxdb/latest/ to the product root, which the old bundle-time replace-docs-url-shortcode decorator never did — it only handled the {{% INFLUXDB_DOCS_URL %}} form. So the v2 reference was shipping 206 links pointing at /influxdb/latest/ instead of /influxdb/v2/. That's the docs-v2 half of #7666, now fixed here.

Nice detail: the \{\{%\s*INFLUXDB_DOCS_URL\s*%\}\} pattern uses \s*, so it also catches the malformed {{% INFLUXDB_DOCS_URL%}} tag in upstream src/common/paths/me_password.yml:50. Both builds show 0 literal shortcodes, but the new one is robust to that upstream typo rather than incidentally unaffected by it.

Everything else in the built output is identical — same paths, same tags, no components added or removed. The 44 differing paths and the After/Offset/securitySchemes component changes are all this URL rewrite.

Tests

All 52 pass, including the 7 new mirror-transform cases (14a–14g) and — the part I'd have asked for — 15a–15c asserting non-mirror products are left untouched, so Core/Enterprise/Clustered aren't silently affected by the docs/mirror split.

Net effect on the original goal

The committed v2 specs are now clean mirrors of upstream, so a sync diff shows upstream content drift and nothing else. Combined with the Redocly pin, the first OSS sync PR should be exactly the 9-line onConflict addition I measured earlier.

I'll add a note to #7666 narrowing its scope: with this merged, the remaining upstream defects (doubled /influxdb/latest/influxdb/latest/ segments in src/oss/tags.yml:148-149, and the malformed tag) no longer affect docs-v2 output — the doubled URLs never reached our build anyway, since our own tags.yml overrides that tag description. #7666 is now purely about other consumers of the raw contract.

---

Generated by Claude Code

[jstirnaman]

Steps to prevent publishing the unimplemented param until the influxdb work is completed:

1. Merge feat(api): automate Cloud and OSS v2 spec sync #7697.
2. gh workflow run sync-openapi-oss-v2-spec.yml — dispatches immediately, resolves
   current master, opens/updates sync/openapi-oss-v2-spec PR with onConflict diff.
3. On that generated PR: add waiting:pr (blocked on influxdb#27585 merging) or
   waiting:engineering if status unclear, plus release:pending.
4. Comment linking feat: Update openapi contracts to include onConflict parameter for restore openapi#655 and feat: handle bucket conflicts for restore  influxdb#27585 so reviewers
   see why it's held.

[jstirnaman]

That plan works — I measured step 2's output earlier and it's a clean 9-line diff adding onConflict to PostRestoreBucketMetadata, nothing else. All four labels you'd use (waiting:pr, waiting:engineering, release:pending, release:ready) exist in the repo.

Two things about holding that generated PR open for a long stretch, since influxdb#27585 is still a draft against main-2.x and then needs a 2.x release after it merges.

1. The generated PR won't have CI. create-pull-request uses GITHUB_TOKEN, which by design can't trigger on: pull_request workflows — all 12 of this repo's PR checks will be absent, including pr-link-check, pr-vale-check, pr-render-check, and preview. That's the one Copilot finding still open, and it's pre-existing for sync-plugins, sync-client-library-release-notes, and check-pinned-deps too. It matters more here than usual: the held PR is a spec change nobody will have seen rendered, sitting until someone merges it months later on the strength of a review done today. Worth either resolving the App-token question first, or running bash api-docs/generate-api-docs.sh locally against that branch at merge time.

2. The held PR's diff will grow silently. Each Monday run pushes to the same fixed sync/openapi-oss-v2-spec branch and updates the existing PR. So while it sits waiting on the release, every unrelated influxdata/openapi master change lands in it too. The labels persist, the title stays the same, and the diff quietly stops being "just onConflict."

Suggestion for step 4's comment: state the SHA the PR was reviewed at, so whoever merges it knows to re-check the diff rather than trusting the original review. Alternatively, dispatch on demand once #27585 merges instead of letting the weekly schedule accumulate into a held PR — you'd get the same result with a diff that matches its review.

---

Generated by Claude Code