fix(ci): commit regenerated OpenAPI artifact (audit #118)

[KooshaPari]

User description

Summary

Audit #118 flagged that .github/workflows/openapi-docs.yml regenerates the OpenAPI spec on every push but the spec artifact never reaches origin — "invisible generator" drift. Consumers (SDK generators, docs site, contract tests) cannot fetch a current contract from the repo.

Root cause: the deploy-to-docs-site job already contained a commit-and-push step, but was missing permissions: contents: write (so the default GITHUB_TOKEN could not push) and the checkout did not persist credentials against main.

Changes

• Add permissions: contents: write to deploy-to-docs-site job.
• Checkout with explicit ref: main, persist-credentials: true, token: ${{ secrets.GITHUB_TOKEN }}.
• Scope the diff check to the two spec files; explicit git push origin HEAD:main.
• Use github-actions[bot] noreply identity (Phenotype convention).
• Keep [skip ci] on the commit message to avoid recursive triggers.

Why Option A (auto-commit) vs C (PR)

Job was already wired for auto-commit — just broken. Kept intent; documented that peter-evans/create-pull-request@v7 is an easy swap if the team later wants human review on contract changes.

.gitignore

backend/docs/ is ignored intentionally (swag build artifact). Canonical committed spec lives at docs/public/openapi.{json,yaml} which is not ignored. No negation needed.

Test plan

• Merge; next push to main touching backend/**/*.go triggers regeneration.
• Confirm a follow-up chore(openapi): regenerate spec artifact [skip ci] commit appears on main with updated docs/public/openapi.{json,yaml}.
• Confirm [skip ci] prevents recursive workflow trigger.

Ref: worklogs/ARCHITECTURE.md 2026-04-24 OpenAPI/spec coverage audit.

🤖 Generated with Claude Code

Note

Medium Risk
Changes CI to push commits to main using GITHUB_TOKEN, which can create unintended repo writes or loops if misconfigured, but scope is limited to two spec files and uses [skip ci].

Overview
Ensures the deploy-to-docs-site GitHub Actions job can commit and push regenerated OpenAPI specs back to main.

The workflow now grants contents: write, checks out main with persisted credentials, and only commits when docs/public/openapi.{json,yaml} changed, pushing explicitly via git push origin HEAD:main with the github-actions[bot] identity and a [skip ci] commit message.

^{Reviewed by Cursor Bugbot for commit 0dd90b5. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

CodeAnt-AI Description

Keep the OpenAPI spec committed to the repo after regeneration

What Changed

• The OpenAPI docs workflow can now push updated spec files back to main after regeneration.
• If the generated openapi.json or openapi.yaml changes, the workflow commits them with a bot identity and skips CI to avoid повторный trigger loops.
• If the spec files do not change, the workflow exits without creating a commit.

Impact

✅ Current OpenAPI specs stay available in the repo
✅ Fewer stale contract files after backend changes
✅ No extra CI runs from spec auto-updates

🔄 Retrigger CodeAnt AI Review

Details

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[codeant-ai]

CodeAnt AI is reviewing your PR.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[coderabbitai]

Note

.coderabbit.yaml has unrecognized properties

CodeRabbit is using all valid settings from your configuration. Unrecognized properties (listed below) have been ignored and may indicate typos or deprecated fields that can be removed.

⚠️ Parsing warnings (1)

Validation error: Unrecognized key(s) in object: 'pre_merge_checks', 'pr_validation'

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

📝 Walkthrough

Walkthrough

The OpenAPI docs workflow now uses explicit GitHub token permissions and the default github-actions[bot] identity. It replaces the previous commit detection with a git status --porcelain check against OpenAPI output files, conditionally commits with a [skip ci] message, and provides explicit feedback when no changes occur.

Changes

Cohort / File(s)	Summary
Workflow Configuration .github/workflows/openapi-docs.yml	Updated permissions to explicitly request contents: write, switched Git identity from custom "OpenAPI Bot" to github-actions[bot], and replaced change detection logic to use git status --porcelain with conditional commit/push and explicit no-op handling.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Permissions granted, credentials persist,
GitHub's bot now commits with a fist,
Status checks shine, no diffs in the night,
OpenAPI specs flow, oh what a sight!
[skip ci] hops along, trouble-free and light!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: fixing the CI workflow to commit regenerated OpenAPI artifacts, with reference to the audit.
Description check	✅ Passed	The description is thorough and covers key sections: problem statement, detailed changes, justification for design choice, and test plan. Required template sections are adequately addressed.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/ci-commit-openapi-artifact

---

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 and usage tips.}

[codeant-ai]

CodeAnt AI finished reviewing your PR.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

.github/workflows/openapi-docs.yml (1)

126-166: ⚠️ Potential issue | 🟠 Major

Add a concurrency group (and/or push retry) to avoid racing self-commits to main.

The deploy job now pushes directly to main, but nothing serializes runs. If two qualifying pushes land close together (e.g. a feature merge followed quickly by another, or a bulk merge), two deploy-to-docs-site jobs run in parallel, both check out main, and whichever pushes second fails with a non-fast-forward (no git pull --rebase/retry). Worse, with ref: main each run checks out whatever main is at the time of the checkout, so a later-triggered run can commit an older artifact on top of a newer one from a concurrent run, causing artifact flap until the next trigger.

Two low-cost mitigations (pick one, ideally both):

🔧 Proposed fix — serialize the deploy job and add a rebase-retry on push

   deploy-to-docs-site:
     name: Deploy to Docs Site
     runs-on: ubuntu-latest
     needs: generate-and-validate
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     permissions:
       contents: write
+    concurrency:
+      group: openapi-docs-deploy-main
+      cancel-in-progress: false

       - name: Commit and push if changed
         run: |
           git config user.name 'github-actions[bot]'
           git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
           git add docs/public/openapi.json docs/public/openapi.yaml
           if [ -n "$(git status --porcelain docs/public/openapi.json docs/public/openapi.yaml)" ]; then
             git commit -m "chore(openapi): regenerate spec artifact [skip ci]"
-            git push origin HEAD:main
+            for i in 1 2 3; do
+              git pull --rebase --autostash origin main && git push origin HEAD:main && break
+              echo "Push attempt $i failed, retrying..."
+              sleep $((i * 5))
+            done
           else
             echo "No OpenAPI spec changes to commit."
           fi

The concurrency group prevents overlapping runs on main and removes the race entirely; the rebase-retry handles the remaining edge case where an unrelated push lands between checkout and push.

Per the PR objectives, [skip ci] is relied on to prevent recursive triggers — note that commits authored via the default GITHUB_TOKEN already don't trigger further workflow runs by design, so this is belt-and-suspenders and not a concern on its own.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/openapi-docs.yml around lines 126 - 166, The
deploy-to-docs-site job is racy when multiple pushes to main trigger
simultaneous runs; add a concurrency stanza to the job (e.g., concurrency: {
group: "deploy-docs-site-main", cancel-in-progress: false }) to serialize runs
and update the "Commit and push if changed" step to perform a safe retry/rebase
before push (detect non-fast-forward, run git pull --rebase origin main and
re-add/commit, retry push a few times with backoff) so the sequence in the
"Checkout code" and "Commit and push if changed" steps handles intervening
commits and avoids failed/non-fast-forward pushes.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In @.github/workflows/openapi-docs.yml:
- Around line 126-166: The deploy-to-docs-site job is racy when multiple pushes
to main trigger simultaneous runs; add a concurrency stanza to the job (e.g.,
concurrency: { group: "deploy-docs-site-main", cancel-in-progress: false }) to
serialize runs and update the "Commit and push if changed" step to perform a
safe retry/rebase before push (detect non-fast-forward, run git pull --rebase
origin main and re-add/commit, retry push a few times with backoff) so the
sequence in the "Checkout code" and "Commit and push if changed" steps handles
intervening commits and avoids failed/non-fast-forward pushes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: cb207c21-5f46-4c3d-b206-543c515ad530

📥 Commits

Reviewing files that changed from the base of the PR and between ab5f80f and 0dd90b5.

📒 Files selected for processing (1)

• .github/workflows/openapi-docs.yml

[codeant-ai]

CodeAnt AI is running the review.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[codeant-ai]

CodeAnt AI finished running the review.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[codeant-ai]

CodeAnt AI is running the review.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[codeant-ai]

CodeAnt AI finished running the review.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[codeant-ai]

CodeAnt AI is running the review.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[codeant-ai]

CodeAnt AI finished running the review.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[codeant-ai]

CodeAnt AI is running the review.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[codeant-ai]

CodeAnt AI finished running the review.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn