fix: documentation deployment

[tac0turtle]

Overview

Documentation deployment

Summary by CodeRabbit

• Chores
  • Refined GitHub Actions workflows for documentation deployment and preview generation to streamline the publishing process.

[github-actions]

The latest Buf updates on your PR. Results from workflow CI / buf-check (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	⏩ skipped	✅ passed	✅ passed	Mar 23, 2026, 4:28 PM

[claude]

Claude finished @tac0turtle's task in 43s —— View job

---

Code Review: PR #3190 — fix: documentation deployment

Tasks

• Read changed workflow files
• Analyze security, correctness, and best practices
• Post review

---

Summary

This PR makes two targeted fixes to the documentation CI/CD workflows:

1. docs_deploy.yml — Scopes permissions to contents: write at the workflow level and switches the deploy token from secrets.PAT_DOCS to secrets.GITHUB_TOKEN.
2. docs_preview.yml — Adds a step to clear the Git http.extraheader credential before running the preview deploy action.

Both changes are correct and improve security posture. A few observations below.

---

.github/workflows/docs_deploy.yml

✅ Token switch (PAT_DOCS → GITHUB_TOKEN) — Good

Using GITHUB_TOKEN instead of a long-lived PAT reduces credential scope and eliminates the risk of a leaked/expired PAT breaking deployments. The peaceiris/actions-gh-pages action supports GITHUB_TOKEN natively.

⚠️ permissions: contents: write is set at workflow level, not job level

The permission is declared at the top-level permissions: block (line 22–23), which applies to all jobs in the workflow. Currently there is only one job (build), so this is benign, but it's worth noting that if additional jobs are added in the future they'll inherit write access. Consider moving it to the job level:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write

⚠️ Missing pages: write and id-token: write for actions/configure-pages

actions/configure-pages@v5 and the subsequent peaceiris/actions-gh-pages@v4 may need pages: write and id-token: write depending on how GitHub Pages is configured in the repository settings. If the deployment is working, this isn't blocking — but it's worth validating against the action's documented minimum permissions.

ℹ️ yarn install (no --frozen-lockfile) — Line 44 uses yarn install without --frozen-lockfile, while docs_preview.yml uses --frozen-lockfile. For reproducibility and catching lockfile drift, the deploy workflow should match:

run: yarn install --frozen-lockfile

Fix this →

---

.github/workflows/docs_preview.yml

✅ git config --unset-all http.extraheader — Correct fix

The actions/checkout action injects a http.https://github.com/.extraheader credential into the local Git config (containing the GITHUB_TOKEN). When pr-preview-action subsequently tries to push to the external evstack/docs-preview repo using secrets.PREVIEW_DEPLOY, this injected header can conflict and cause auth failures. Unsetting it before the deploy step is the correct fix.

The || true guard is appropriate — it prevents the step from failing if the header doesn't exist.

⚠️ permissions: write-all — Overly broad (flagged by CodeRabbit)

Line 21 uses write-all, which grants every possible write permission to the job. This is excessive; the job only needs to:

• Read the checkout (contents: read)
• Post a PR comment (pull-requests: write) — required by pr-preview-action to post the preview URL

permissions:
  contents: read
  pull-requests: write

The actual push to evstack/docs-preview is handled by secrets.PREVIEW_DEPLOY (an external token), so contents: write on the calling repo is not needed.

Fix this →

---

Overall Assessment

The core fixes are correct and the PR achieves its goal. The write-all permission concern is the only actionable security issue worth addressing in a follow-up. Everything else is minor polish.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4be1faf6-614a-4287-806c-7d6c48e9814a

📥 Commits

Reviewing files that changed from the base of the PR and between 2e6b4ca and 39927c8.

📒 Files selected for processing (1)

• .github/workflows/docs_preview.yml

---

📝 Walkthrough

Walkthrough

This pull request updates GitHub Actions workflows for documentation deployment and preview processes. The changes modify authentication mechanisms by adding explicit job-level permissions to the deployment workflow, switching the deployment token from a personal access token to GitHub's default token, and disabling credential persistence in the preview workflow's checkout step.

Changes

Cohort / File(s)	Summary
Documentation Deployment Workflow .github/workflows/docs_deploy.yml	Added explicit permissions: contents: write at job level and switched the GitHub Pages deployment authentication token from secrets.PAT_DOCS to secrets.GITHUB_TOKEN.
Documentation Preview Workflow .github/workflows/docs_preview.yml	Updated checkout step to set persist-credentials: false, disabling Git credential persistence during the checkout phase.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• fix: documentation deployment #3190: Modifies the same workflow files (docs_deploy.yml and docs_preview.yml) with similar authentication and credential handling changes.

Suggested reviewers

• julienrbrt

Poem

🐰 With whiskers twitching and a hop of delight,
Token permissions set, credentials held tight,
GitHub's own secrets now guard what we share,
Documentation flows freely through the CI air! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is largely incomplete, containing only a single line 'Documentation deployment' under the Overview section with no context, rationale, or details about the changes.	Expand the Overview section with details about what deployment issues were fixed, why the workflow changes were necessary, and the impact of switching authentication tokens.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix: documentation deployment' directly addresses the main changes in the PR, which involve updating deployment workflows and documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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 marko/update_docs

---

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.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 61.14%. Comparing base (fa686cb) to head (39927c8).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3190   +/-   ##
=======================================
  Coverage   61.13%   61.14%           
=======================================
  Files         117      117           
  Lines       12082    12082           
=======================================
+ Hits         7386     7387    +1     
  Misses       3869     3869           
+ Partials      827      826    -1     

Flag	Coverage Δ
combined	61.14% <ø> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[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/docs_preview.yml (1)

21-21: ⚠️ Potential issue | 🟠 Major

Avoid permissions: write-all; scope to least privilege.

Granting all write permissions exposes the workflow to unnecessary risk if any step is compromised. Since this job only deploys docs preview content, consider narrowing to only the permissions required:

🔒 Proposed fix to scope permissions

-    permissions: write-all
+    permissions:
+      contents: read
+      pull-requests: write   # if pr-preview-action needs to comment

Adjust as needed based on what rossjrw/pr-preview-action actually requires (typically contents: read for checkout and the external PREVIEW_DEPLOY token handles the push).

🤖 Prompt for AI Agents

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

In @.github/workflows/docs_preview.yml at line 21, Replace the broad
"permissions: write-all" key with narrowly-scoped permissions for this job: set
"permissions" to only what the job needs (for example "contents: read" and, if
the pr-preview action requires it for pushing, "contents: write" only when using
the PREVIEW_DEPLOY token), and mention the action "rossjrw/pr-preview-action" in
the change so the scope matches its documented requirements; remove any other
write privileges not required by the docs preview workflow.

🤖 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/docs_preview.yml:
- Line 21: Replace the broad "permissions: write-all" key with narrowly-scoped
permissions for this job: set "permissions" to only what the job needs (for
example "contents: read" and, if the pr-preview action requires it for pushing,
"contents: write" only when using the PREVIEW_DEPLOY token), and mention the
action "rossjrw/pr-preview-action" in the change so the scope matches its
documented requirements; remove any other write privileges not required by the
docs preview workflow.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: dcb28ae6-07b9-43eb-92d0-ab99e785eb13

📥 Commits

Reviewing files that changed from the base of the PR and between 766399a and 2e6b4ca.

📒 Files selected for processing (2)

• .github/workflows/docs_preview.yml
• docs/README.md

✅ Files skipped from review due to trivial changes (1)

• docs/README.md

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://evstack.github.io/docs-preview/pr-3190/
Built to branch main at 2026-03-23 15:29 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[julienrbrt]

utACK