[WIP] Add pre-flight token permission validation for safe operations

[Copilot]

Pre-flight Token Permission Validation for Safe Outputs

Completed

• Research GitHub API token scope/permission validation
• Create token validation utility in actions/setup/js/token_permissions.cjs
• Add permission mapping for safe output operations
• Integrate validation into safe output handler managers
• Add comprehensive tests for permission validation

In Progress

• Test with insufficient permissions scenario
• Update documentation

Implementation Details

Token Permission Validator (token_permissions.cjs)

• ✅ Queries GitHub API for token scopes/permissions via x-oauth-scopes header
• ✅ Maps safe output operations to required permissions
• ✅ Supports both classic PATs (OAuth scopes) and fine-grained PATs
• ✅ Returns validation results with missing permissions and remediation steps

Handler Manager Integration

• ✅ Pre-flight validation in safe_output_handler_manager.cjs
• ✅ Pre-flight validation in safe_output_project_handler_manager.cjs
• ✅ Fail fast with clear error messages
• ✅ Include remediation steps in error messages
• ✅ Warning (not error) for optional permissions

Permission Mappings Defined

• create_issue: issues: write
• add_comment: issues: write OR pull_requests: write (requires any)
• update_project: projects: write (+ optional issues: write for labels)
• create_pull_request: pull_requests: write, contents: write
• And 20+ other safe output operations

Tests

• ✅ 26 comprehensive test cases covering all validation scenarios
• ✅ Tests for permission requirements, error messages, and warnings
• ✅ All tests passing

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Add pre-flight token permission validation for safe output operations</issue_title>
<issue_description>### Description

Safe output operations currently fail silently when GitHub tokens lack required permissions (e.g., issues: write for adding labels). Operations continue with warnings, but users don't get clear feedback about missing permissions until after execution begins. This leads to degraded functionality without clear root cause indication.

Problem

Current Behavior:

• Safe output handler attempts operations
• Permission failures result in warnings: ##[warning]Failed to add campaign label: Resource not accessible by personal access token
• Operations complete "successfully" but with reduced functionality
• Users must dig through logs to find permission issues

Example from Production:

• 10 occurrences of campaign label permission failures in run §21496931510
• Token GH_AW_PROJECT_GITHUB_TOKEN lacks issues: write permission
• All update_project operations degraded silently

Impact

• User Experience: Confusing silent failures
• Debugging Time: Must read logs to identify permission issues
• Operational Quality: Features disabled without clear indication
• Error Messages: Not actionable until after partial execution

Suggested Changes

Add pre-flight permission validation in safe output handler manager:

Implementation Approach:

1. Query GitHub API for token scopes/permissions before execution
2. Compare against required permissions for planned operations
3. Fail fast with clear error if permissions are insufficient
4. Warn if optional permissions are missing (e.g., label management)

Required Permissions Map:

• create_issue: issues: write
• add_comment: issues: write or pull_requests: write
• update_project: project: write, optionally issues: write for labels
• create_pull_request: pull_requests: write, contents: write

Files Affected

Primary implementation:

• actions/setup/js/safe_output_manager.cjs (or equivalent handler manager)
• Add validatePermissions() function to check token scopes

Success Criteria

• Pre-flight permission check queries token scopes via GitHub API
• Clear error message if required permissions are missing
• Warning (not error) if optional permissions are missing
• Error message includes remediation steps (which scopes to add)
• Unit tests cover permission validation logic
• Integration test with token that lacks permissions

Source

Extracted from Safe Output Health Report - 2026-01-29

Finding: Error Cluster #1 - Campaign Label Permission Errors (10 occurrences)

Priority

Medium - Improves user experience and debuggability significantly, but current graceful degradation prevents critical failures.

Estimated Effort

2-4 hours (implementation + testing)

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 13, 2026, 5:22 AM UTC

Comments on the Issue (you are @copilot in this section)

• Fixes [Code Quality] Add pre-flight token permission validation for safe output operations #12676

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.