Add OpenAPI generation workflow

[brendan-kellam]

Summary

• add a pull_request workflow to regenerate the public OpenAPI spec when web code or the shared version changes
• commit regenerated spec changes back to same-repo PR branches

Testing

• not run; workflow-only change

Summary by CodeRabbit

• Chores
  • Added an automated check for pull requests that regenerates the public API specification when relevant web or version changes are made.
  • If the generated API spec changes, it is automatically committed back to the branch, helping keep published API docs current.

[github-actions]

@brendan-kellam your pull request is missing a changelog!

[coderabbitai]

Walkthrough

Adds a new GitHub Actions workflow that triggers on PRs to main when files under packages/web/** or packages/shared/src/version.ts change. It installs dependencies, generates the OpenAPI spec via the @sourcebot/web workspace command, and commits the result to docs/api-reference/sourcebot-public.openapi.json if the file changed. Fork PRs are skipped.

Changes

OpenAPI Spec Auto-generation Workflow

Layer / File(s)	Summary
Generate OpenAPI workflow .github/workflows/generate-openapi.yml	Defines the full workflow: PR trigger scoped to specific paths, Node.js 20 + Yarn setup, OpenAPI generation command, conditional commit/push with contents: write permission, and fork-skip guard.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding a workflow to generate the OpenAPI spec.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch brendan/generate-openapi-workflow

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (2)

.github/workflows/generate-openapi.yml (2)

18-23: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Set persist-credentials: false on checkout and configure push auth explicitly.

The checkout step persists the GitHub token in git config by default, which zizmor flags as a credential-persistence risk. While the push step needs authentication, it is safer to disable persistence and configure the remote URL with the token only where needed.

Add persist-credentials: false to the checkout step, then update the push step to use the token explicitly:

      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          submodules: "true"
          ref: ${{ github.head_ref }}
          token: ${{ secrets.GITHUB_TOKEN }}
          persist-credentials: false

And in the commit step, before git push:

          git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}`@github.com/`${{ github.repository }}.git
          git push

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/generate-openapi.yml around lines 18 - 23, The checkout
step in the workflow currently persists the GitHub token in git config, so
update the actions/checkout@v4 configuration to set persist-credentials: false
in the “Checkout repository” step. Then make the push authentication explicit in
the commit/push step by updating the remote URL with the token right before git
push, using the existing GITHUB_TOKEN and the push-related step that performs
the commit.

Source: Linters/SAST tools

---

38-49: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Add pull --rebase before push to avoid race-condition rejections.

If the PR branch receives new commits between checkout and push, the bare git push will fail with a non-fast-forward error. Add a pull-rebase step before pushing:

          git pull --rebase origin ${{ github.head_ref }}
          git push

Additionally, consider whether the OpenAPI generation is fully deterministic. If createPublicOpenApiDocument embeds timestamps, non-sorted schema keys, or environment-dependent values, the workflow could commit spurious diffs on every run. Verify that generation output is stable for identical inputs.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/generate-openapi.yml around lines 38 - 49, The
commit-and-push step in the OpenAPI generation workflow can fail on
non-fast-forward updates, so update the commit block in the workflow to rebase
the current branch before pushing by using the existing git push flow around the
commit step; reference the Commit regenerated spec if changed block and the git
push command. Also review createPublicOpenApiDocument output for stability and
make sure generated spec content is deterministic (no timestamps, unstable key
ordering, or environment-dependent values) so the workflow does not produce
spurious commits.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @.github/workflows/generate-openapi.yml:
- Around line 18-23: The checkout step in the workflow currently persists the
GitHub token in git config, so update the actions/checkout@v4 configuration to
set persist-credentials: false in the “Checkout repository” step. Then make the
push authentication explicit in the commit/push step by updating the remote URL
with the token right before git push, using the existing GITHUB_TOKEN and the
push-related step that performs the commit.
- Around line 38-49: The commit-and-push step in the OpenAPI generation workflow
can fail on non-fast-forward updates, so update the commit block in the workflow
to rebase the current branch before pushing by using the existing git push flow
around the commit step; reference the Commit regenerated spec if changed block
and the git push command. Also review createPublicOpenApiDocument output for
stability and make sure generated spec content is deterministic (no timestamps,
unstable key ordering, or environment-dependent values) so the workflow does not
produce spurious commits.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ba74afbf-a55b-4341-871c-fa0c54f7ef81

📥 Commits

Reviewing files that changed from the base of the PR and between f7f0fef and 983f589.

📒 Files selected for processing (1)

• .github/workflows/generate-openapi.yml