fix(ci): add workflows:write permission to amber-issue-handler

[jeremyeder]

Summary

• Adds workflows: write permission to the amber-issue-handler workflow
• Fixes the "Push branch to remote" step failure when Amber creates/modifies files under .github/workflows/
• GitHub requires explicit workflows permission for any token touching workflow files, even with contents: write

Context

The amber-handler job in run #21777412886 failed because Amber created a nightly-builds.yml workflow file for issue #591, but GitHub rejected the push:

refusing to allow a GitHub App to create or update workflow
`.github/workflows/nightly-builds.yml` without `workflows` permission

Test Plan

• Re-run the amber handler on issue [Amber] nightly builds #591 (or re-label with amber:auto-fix)
• Amber should be able to push branches containing workflow file changes

🤖 Generated with Claude Code

[github-actions]

Claude Code Review

Summary

This PR adds the workflows: write permission to the Amber Issue Handler workflow to fix permission errors when Amber creates or modifies GitHub Actions workflow files. The change is minimal, targeted, and follows GitHub's security model for workflow file modifications.

Issues by Severity

🚫 Blocker Issues

None identified. The change is safe and correctly implements the fix.

🔴 Critical Issues

None identified.

🟡 Major Issues

None identified.

🔵 Minor Issues

1. Missing Documentation Update

• Location: .github/workflows/amber-issue-handler.yml:33
• Issue: The inline comment accurately describes the permission, but there's no corresponding update to project documentation
• Recommendation: Consider adding a note to docs/amber-automation.md or docs/amber-quickstart.md about this permission requirement for workflow automation
• Impact: Low - inline comment is sufficient, but external docs would help future troubleshooting

Positive Highlights

✅ Excellent Problem Diagnosis - The PR clearly identifies the root cause with a link to the failing run and the exact error message

✅ Minimal Change Scope - Only adds the necessary permission, follows principle of least privilege

✅ Clear Documentation - The inline comment # Required to create/update GitHub Actions workflow files matches the style and clarity of other permission comments

✅ Follows Security Best Practices - The permission is scoped to the specific workflow that needs it, not granted globally

✅ Consistent Formatting - The alignment of comments matches existing style (spaces for alignment after id-token: write)

✅ GitHub Security Model Compliance - Correctly implements GitHub's requirement that tokens must have explicit workflows permission to modify .github/workflows/ files, even with contents: write

Recommendations

Priority 1: Safe to Merge ✅

This PR is ready to merge as-is. The change correctly addresses the identified issue and follows all security and coding standards.

Priority 2: Post-Merge Enhancement (Optional)

Consider documenting this permission requirement in user-facing documentation:

# In docs/amber-automation.md or docs/amber-quickstart.md

## Workflow Permissions

The Amber Issue Handler requires the following GitHub Actions permissions:
- `contents: write` - To push commits to branches
- `issues: write` - To comment on issues
- `pull-requests: write` - To create and update PRs
- `workflows: write` - **Required** when Amber creates/modifies workflow files in `.github/workflows/`
- `id-token: write` - For OIDC authentication with cloud providers

Test Plan Validation

The PR mentions re-running Amber on issue #591. After merge, verify:

1. Amber can successfully push branches containing workflow files
2. No other permission errors occur
3. The workflow creation/modification completes successfully

---

Technical Analysis

Change Review

+  workflows: write   # Required to create/update GitHub Actions workflow files

Why This is Correct:

1. GitHub Security Model: GitHub Actions enforces strict separation between code and workflow permissions. The contents: write permission grants write access to repository code, but workflow files in .github/workflows/ require an additional explicit workflows: write permission. This prevents accidental or malicious workflow modifications.

2. Scope Appropriateness: The permission is added only to the amber-issue-handler.yml workflow, which is the specific automation that needs to create/modify workflow files. Other workflows in the repository do not have this permission, maintaining the principle of least privilege.

3. Alignment with Repository Standards: From CLAUDE.md § GitHub Actions CI/CD:

   • The Amber handler is an automation workflow that may touch any file in the repository
   • The change follows established patterns for permission documentation
   • Inline comments match the style and clarity of other workflows

Security Validation

✅ No Privilege Escalation Risk: The permission is scoped to workflow file modifications only, not execution

✅ Audit Trail: All workflow changes pushed by Amber are visible in git history and PR diffs

✅ No Token Exposure: The permission doesn't expose the GitHub token or expand its scope beyond workflow files

✅ Branch Protection Compatible: Standard branch protection rules still apply to workflow file changes

Compliance Check Against Repository Standards

From .claude/context/security-standards.md:

• ✅ No token logging or exposure
• ✅ Follows principle of least privilege
• ✅ Clear documentation of permission purpose
• ✅ No bypass of existing security controls

From CLAUDE.md § Backend and Operator Development Standards:

• ✅ N/A (this is a CI/CD workflow change, not backend/operator code)

From CLAUDE.md § Git Workflow:

• ✅ Conventional commit format: fix(ci): add workflows:write permission to amber-issue-handler
• ✅ Clear commit message body explaining the why and providing reference link

---

Conclusion

Recommendation: ✅ APPROVE AND MERGE

This PR correctly implements the fix for Amber's workflow file permission issue. The change is:

• Minimal and targeted
• Properly documented
• Compliant with GitHub security model
• Following repository standards

No blocking or critical issues identified. The suggested documentation enhancement is optional and can be addressed in a follow-up PR if desired.

---

🔍 View AI decision process (logs available for 90 days)

📋 View memory system files loaded (click to expand)

What Amber Loaded for Code Review

Amber automatically loaded these repository standards from the memory system:

1. CLAUDE.md - Master project instructions, development standards
2. backend-development.md - Go backend, K8s integration patterns
3. frontend-development.md - NextJS, Shadcn UI, React Query patterns
4. security-standards.md - Auth, RBAC, token handling
5. k8s-client-usage.md - User token vs service account patterns
6. error-handling.md - Consistent error patterns
7. react-query-usage.md - Data fetching patterns

Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines.