fix: deploy docs token

[tac0turtle]

Overview

[gemini-code-assist]

Note

Gemini is unable to generate a summary for this pull request due to the file types involved not being currently supported.

[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	Jan 21, 2026, 8:13 PM

[claude]

Claude finished @tac0turtle's task in 1m 18s —— View job

---

Code Review Complete

Summary

This PR makes two changes to the docs deployment workflow:

1. Commit 1 (fd40a2a): Changed the GitHub token from DOCS_DEPLOY_TOKEN to PAT_DOCS (line 49)
2. Commit 2 (8e4d129): Removed the pull_request trigger (line 12)

Review Findings

✅ Positive Aspects

• Simplified trigger logic: Removing the pull_request trigger is appropriate for a deployment workflow, as docs deployments should only happen on pushes to main, not on every PR
• Clean action versions: Using up-to-date action versions (@v6, @v5, @v4)
• Proper concurrency control: The workflow correctly prevents concurrent deployments while allowing in-progress deployments to complete

⚠️ Issues and Recommendations

1. Security: Token Naming and Management
.github/workflows/docs_deploy.yml:49

The token was renamed from DOCS_DEPLOY_TOKEN to PAT_DOCS. However:

• Personal Access Tokens (PATs) should be avoided for deployment workflows when possible. The peaceiris/actions-gh-pages@v4 action can use the built-in GITHUB_TOKEN for deployments to the same repository, which is more secure and doesn't require manual token management.
• If a PAT is truly required (e.g., deploying to a different repository or needing elevated permissions), ensure:
  • The PAT has minimal required scopes (likely just repo or public_repo for gh-pages)
  • The PAT is configured with an expiration date
  • The PAT is not a classic PAT but a fine-grained PAT with repository-specific permissions
• Token naming inconsistency: The change from DOCS_DEPLOY_TOKEN to PAT_DOCS suggests this might be using a shared PAT. Consider whether a dedicated token per use case would be more secure.

Recommendation: Unless you need cross-repository deployment, use the built-in GITHUB_TOKEN:

github_token: ${{ secrets.GITHUB_TOKEN }}

If you must use a PAT, document why in a comment and verify it has minimal permissions.

2. Missing PR Description

The PR has an empty "Overview" section. For infrastructure changes (especially security-related ones like token changes), please document:

• Why the token was renamed
• Whether the old token will be revoked
• What permissions the new token has
• Why the pull_request trigger was removed

3. Workflow Trigger Configuration

.github/workflows/docs_deploy.yml:8-11

The workflow only triggers on pushes to main when docs/** files change. This is good, but consider:

• Should the workflow also run on workflow file changes themselves? Currently, changing .github/workflows/docs_deploy.yml won't trigger the workflow until a docs/** file changes.
• Consider adding the workflow file to the paths:

paths:
  - "docs/**"
  - ".github/workflows/docs_deploy.yml"

4. Minor: Commented Code

.github/workflows/docs_deploy.yml:31

There's commented-out pnpm setup. If not needed, remove it to reduce noise:

# - uses: pnpm/action-setup@v2 # Uncomment this if you're using pnpm

5. Concurrency Group Name

.github/workflows/docs_deploy.yml:19

The concurrency group is named pages which is very generic. If you have multiple workflows deploying to GitHub Pages, they could conflict. Consider:

concurrency:
  group: docs-deploy-pages
  cancel-in-progress: false

Testing Recommendations

Before merging, verify:

1. The new PAT_DOCS secret exists in the repository settings and has the correct permissions
2. The old DOCS_DEPLOY_TOKEN secret should be removed/revoked after this PR is merged
3. The workflow successfully deploys docs when merged to main
4. Confirm that removing the pull_request trigger is intentional and documented

Overall Assessment

The changes are functionally correct but have security and documentation concerns that should be addressed:

• 🔴 High Priority: Verify PAT necessity and permissions scope
• 🟡 Medium Priority: Add PR description explaining the changes
• 🟡 Medium Priority: Consider using GITHUB_TOKEN instead of PAT if possible
• 🟢 Low Priority: Clean up commented code and improve concurrency group naming

The workflow will work as-is, but following GitHub Actions security best practices would make it more maintainable and secure.

---

Todo List

• Read the modified workflow file
• Analyze the git diff to understand the change
• Review token/secrets handling for security issues
• Assess workflow structure and best practices
• Provide comprehensive review feedback

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 58.51%. Comparing base (f70e6da) to head (8e4d129).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3003      +/-   ##
==========================================
- Coverage   58.58%   58.51%   -0.07%     
==========================================
  Files         110      110              
  Lines       10396    10396              
==========================================
- Hits         6090     6083       -7     
- Misses       3662     3669       +7     
  Partials      644      644              

Flag	Coverage Δ
combined	58.51% <ø> (-0.07%)	⬇️

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.