Skip to content

fix: Address CodeRabbit security and correctness feedback on documentation workflow #1386

Description

@ashleyshaw

Summary

CodeRabbit identified security and correctness issues in the consolidated documentation.yml workflow (PR #1317). This issue tracks fixes for:

Issues Identified

Security

  • Overly broad workflow permissions (scope to individual jobs)
  • Missing persist-credentials flags on checkout steps
  • Shell script variable handling security

Correctness

  • Maintenance report misrepresents outcomes (shows success when scripts fail)
  • README resolver over-includes root README on every change
  • Documentation lacks clarity on output format (comma-separated vs space-separated)

Solution

Branch: fix/workflows-documentation-security-hardening

Changes Included

  1. Job-scoped permissions — Remove overly broad top-level permissions; scope to audit, regenerate, maintain jobs
  2. persist-credentials flags — Set to false for read-only (audit), true for write operations
  3. Maintenance report accuracy — Track individual step outcomes; display actual success/failure status
  4. README resolver optimization — Only add root README when subdirectory files change
  5. Enhanced documentation — Comments explaining output format, execFileSync security rationale

Related Issues


Definition of Ready (DoR)

  • Bug is reproducible and clearly described
  • Steps to reproduce written
  • Environment details provided
  • Linked to existing issues/PRs (if any)
  • Ready for triage

Definition of Done (DoD)

  • Bug confirmed and reproducible
  • Fix implemented and tested
  • Follows coding standards
  • Changelog entry prepared for PR (CHANGELOG.md)
  • Security: job-scoped permissions and persist-credentials applied
  • Performance: no adverse impact introduced
  • QA performed
  • Linked issue closed

Related issues: #1227, #1309, #1310, #1317

Metadata

Metadata

Assignees

Type

No type

Fields

Priority

None yet

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions