Fix GitHub Actions scheduled workflow issues

[AodhanHayter]

Summary

This PR fixes issues preventing the scheduled workflow from running:

1. Fixed YAML syntax error - Removed problematic heredoc syntax on line 117
2. Added workflow documentation - Documented GitHub's scheduling requirements
3. Optimized cron schedule - Changed to run at 15 minutes past the hour to avoid peak times
4. Added diagnostic script - Created script to check workflow health
5. Added workflow status badge - Shows workflow status in README

Changes Made

• Fixed commit message formatting in workflow to avoid YAML parsing issues
• Added comprehensive comments about GitHub's scheduled workflow requirements
• Created diagnostic script to help troubleshoot future issues
• Updated README with workflow status badge and documentation

Testing

• Created test workflows to verify triggers work correctly
• Confirmed manual dispatch trigger functions properly
• Scheduled triggers will activate once merged to master

Notes

GitHub scheduled workflows have specific requirements:

• Only run on the default branch
• Automatically disabled after 60 days of inactivity
• Must be pushed to default branch before schedule activates

The diagnostic script at scripts/check-workflow-schedule.sh can be used to monitor workflow health.

[claude]

Claude finished @AodhanHayter's task —— View job

---

PR Review: Fix GitHub Actions scheduled workflow issues

Review Tasks:

• Read repository guidelines (CLAUDE.md)
• Review scheduled-update.yml workflow
• Review test-workflow.yml workflow
• Review update-opencode-fixed.yml workflow
• Analyze code quality and best practices
• Check for potential bugs and security issues
• Assess test coverage and workflow logic
• Provide comprehensive feedback and recommendations

---

✅ Overall Assessment

This PR successfully addresses GitHub Actions workflow issues and implements a robust automated update system. The code quality is generally good with comprehensive error handling and documentation.

🔧 Code Quality & Best Practices

Strengths:

• Excellent documentation: Clear comments explaining GitHub's scheduling requirements (update-opencode-fixed.yml:3-11)
• Smart cron timing: Using 15 */6 * * * avoids GitHub's peak times
• Comprehensive error handling: Proper handling of merge failures and cleanup operations
• Modular approach: Well-structured workflow with clear job separation
• Good git practices: Proper bot user configuration and co-authored commits

Areas for Improvement:

1. Inconsistent workflow naming: Three different patterns used (Scheduled OpenCode Update, Test Workflow, Update OpenCode (Fixed))
2. Token handling inconsistency: scheduled-update.yml:18 uses fallback pattern while update-opencode-fixed.yml:38 requires token

🐛 Potential Bugs & Issues

Critical Issues:

1. Package reference mismatch (update-opencode-fixed.yml:58,74,97):

   CURRENT_VERSION=$(grep -o 'version = "[^"]*"' package.nix | head -1 | sed 's/version = "\(.*\)"/\1/')

   • References package.nix but actual file uses different format: version = "0.5.29";
   • Should be: grep -o 'version = "[^"]*";' package.nix

2. Missing nix-update-script dependency (update-opencode-fixed.yml:68):

   • Workflow calls nix-update opencode --use-update-script
   • But package.nix:170-177 shows the update script expects --subpackage args
   • Command should be: nix-update opencode --use-update-script --subpackage tui --subpackage node_modules

3. Potential merge conflicts (update-opencode-fixed.yml:141-156):

   • Uses git checkout ${{ github.ref_name }} which may not be 'master'
   • Should explicitly checkout master for scheduled workflows

Minor Issues:

4. Test workflow pollution (test-workflow.yml:10):

   • Runs every 15 minutes which could spam logs
   • Should only activate for testing purposes

5. Incomplete placeholder logic (scheduled-update.yml:28-33):

   • Contains echo statements but no actual update implementation

🔒 Security Concerns

Low Risk:

• Appropriate use of PERSONAL_ACCESS_TOKEN with proper fallback
• Correct permissions scope (contents: write)
• Secure git configuration using bot account

Recommendations:

• Consider using GitHub's GITHUB_TOKEN with enhanced permissions instead of PAT if possible
• Validate version inputs to prevent injection in manual dispatch

🧪 Test Coverage

Positive:

• Good test workflow for verifying triggers (test-workflow.yml)
• Version testing implemented in package (package.nix:165-169)
• Manual dispatch capability for testing

Missing:

• No integration tests for the actual update process
• No validation of generated releases
• No rollback mechanism for failed updates

📋 Specific Recommendations

High Priority Fixes:

1. Fix version extraction regex in update-opencode-fixed.yml:58,74,97
2. Correct nix-update command parameters in update-opencode-fixed.yml:68
3. Ensure master branch checkout in update-opencode-fixed.yml:141

Medium Priority Improvements:

1. Standardize workflow naming convention
2. Add input validation for manual version dispatch
3. Implement the actual update logic in scheduled-update.yml

Low Priority Enhancements:

1. Add workflow status badges as mentioned in PR description
2. Create diagnostic script mentioned in PR description
3. Reduce test workflow frequency or make it conditional

🎯 Summary

This PR demonstrates excellent understanding of GitHub Actions and automation best practices. The workflow design is solid with good error handling and documentation. However, there are a few critical bugs that need fixing before merge, particularly around the version extraction and nix-update command usage.

Recommendation: Request changes to fix the critical issues, then this will be ready to merge.

---

[claude]

Claude finished @AodhanHayter's task —— View job

---

PR Review Complete ✅

Review Checklist:

• Examine repository structure and branch changes
• Review GitHub Actions workflow files
• Check for diagnostic script mentioned in PR description
• Verify README updates and workflow badge
• Assess YAML syntax and formatting
• Evaluate security considerations
• Check performance and best practices
• Provide comprehensive feedback

---

Overall Assessment

This PR addresses GitHub Actions scheduled workflow issues with good documentation and tooling. However, there are some discrepancies and issues that need attention.

🔍 Key Findings

✅ Strengths

1. Comprehensive Documentation: The workflow file (update-opencode.yml:3-11) includes excellent comments about GitHub's scheduled workflow requirements and limitations.

2. Smart Cron Scheduling: Changed to 15 */6 * * * (update-opencode.yml:17) to avoid peak times - this is a best practice.

3. Useful Diagnostic Script: scripts/check-workflow-schedule.sh is well-written with proper error handling and helpful diagnostics.

4. README Badge Added: Workflow status badge properly added to README (README.md:3).

5. Robust Error Handling: The workflow includes good error handling for merge conflicts and cleanup.

⚠️ Issues & Concerns

1. Major Discrepancy - Missing Changes

Severity: High

The PR description claims several changes were made, but GitHub shows 0 additions/deletions and 0 files changed. This suggests either:

• Changes were made in previous commits and this PR needs to be rebased
• The PR description doesn't match the actual changes
• There may be an issue with the branch state

Recommendation: Verify the branch state and ensure all claimed changes are actually present.

2. Workflow File Reference Mismatch

Severity: Medium

The diagnostic script (scripts/check-workflow-schedule.sh:9,37,80,95) references update-opencode-nix.yml but the actual workflow file is named update-opencode.yml.

Lines with issues:

WORKFLOW_FILE=".github/workflows/update-opencode-nix.yml"  # Line 9
gh run list --workflow=update-opencode-nix.yml             # Line 37  
gh workflow run update-opencode-nix.yml                    # Line 92

Fix needed:

WORKFLOW_FILE=".github/workflows/update-opencode.yml"

3. Potential Security Issues

Severity: Medium

1. Personal Access Token Usage: The workflow uses secrets.PERSONAL_ACCESS_TOKEN (line 36) which should be scoped minimally. Consider using GitHub App tokens instead for better security.

2. Automatic Merging: The workflow automatically merges to master without PR review, which bypasses code review processes.

4. Workflow Logic Issues

Severity: Low-Medium

1. Version Detection Logic: Lines 95-96 in the workflow assume nix-update will update to the manually specified version, but this may not always be the case.

2. Branch Cleanup: The cleanup step (lines 207-217) might fail if the workflow is interrupted, leaving orphaned branches.

5. Performance Considerations

1. Heavy Operations: The workflow runs nix-update --build which could be resource-intensive. Consider splitting build verification into a separate job.

2. Cron Frequency: Running every 6 hours may be excessive for a project that doesn't update frequently. Consider daily updates instead.

6. Code Quality Issues

1. YAML Formatting: The multi-line commit message (lines 116-120) uses proper YAML syntax, which is good.

2. Shell Script Quality: The diagnostic script follows good practices with set -euo pipefail and proper error handling.

📋 Recommendations

High Priority

1. Fix the diagnostic script filename references to match the actual workflow file
2. Clarify the PR state - ensure all described changes are actually present
3. Review security model for the personal access token usage

Medium Priority

1. Consider adding a PR-based update process instead of direct master merges
2. Add workflow run notifications/alerts for failures
3. Consider reducing update frequency to daily rather than every 6 hours

Low Priority

1. Add more comprehensive error reporting in the workflow
2. Consider adding test validation before auto-merging
3. Add branch protection rules to require PR reviews

🏆 Conclusion

The concepts and implementation are solid, but there are critical inconsistencies between the PR description and actual changes, plus a filename mismatch in the diagnostic script that will cause it to fail. Once these issues are resolved, this will be a robust automation solution.

Status: ⚠️ Needs fixes before merge

---

[claude]

Claude finished @AodhanHayter's task —— View job

---

PR Review: Fix GitHub Actions scheduled workflow issues

Review Tasks:

• Read repository guidelines (CLAUDE.md)
• Review the modified workflow file
• Analyze code quality and best practices
• Check for potential bugs and security issues
• Assess performance considerations
• Evaluate test coverage aspects
• Provide comprehensive feedback and recommendations

---

✅ Overall Assessment

This PR successfully consolidates the workflow improvements into a single, well-structured automated update system. The workflow demonstrates good understanding of GitHub Actions best practices and Nix ecosystem requirements.

🔧 Code Quality & Best Practices

Strengths:

• Excellent documentation: Comprehensive comments about GitHub's scheduling requirements (.github/workflows/update-opencode.yml:3-11)
• Smart scheduling: Uses 15 */6 * * * to avoid GitHub's peak times at the top of the hour
• Proper Nix integration: Correctly leverages nix-update-script with appropriate extraArgs for subpackages
• Robust error handling: Comprehensive error handling for merge failures with clear messaging
• Git best practices: Proper bot configuration and commit message formatting
• Branch strategy: Creates temporary branches for updates, then merges to master - good isolation

Areas for Improvement:

1. Version extraction pattern: Lines 56, 72, 95 use inconsistent regex that may not match the actual file format
2. Merge strategy could be more robust: Current approach assumes fast-forward merges will always work

🐛 Potential Bugs & Issues

Critical Issues:

1. Version regex mismatch (.github/workflows/update-opencode.yml:56,72,95):

   # Current regex
   grep -o 'version = "[^"]*"' package.nix
   
   # But package.nix:25 actually contains
   version = "0.5.29";

   Fix needed: Add semicolon to regex: 'version = "[^"]*";'

2. Potential merge conflicts (.github/workflows/update-opencode.yml:136-137):

   git checkout ${{ github.ref_name }}
   git pull origin ${{ github.ref_name }}

   For scheduled workflows, github.ref_name should always be master, but this could be fragile. Consider hardcoding for scheduled events.

Minor Issues:

3. Branch checkout in cleanup (.github/workflows/update-opencode.yml:213):

   • Uses same ${{ github.ref_name }} pattern which could theoretically fail
   • Should be safe since cleanup runs with || true but worth noting

4. Manual version handling (.github/workflows/update-opencode.yml:82-101):

   • The logic assumes nix-update will update to the manually specified version
   • In practice, nix-update fetches the latest available version, not a specific version
   • This could lead to confusion if manual version is outdated

🔒 Security Assessment

Good Security Practices:

• ✅ Uses secrets.PERSONAL_ACCESS_TOKEN appropriately
• ✅ Proper permissions scope (contents: write)
• ✅ Bot account configuration prevents attribution issues
• ✅ No hardcoded secrets or sensitive data

Security Considerations:

• PAT vs GITHUB_TOKEN: Using PAT is necessary here since the workflow needs to trigger other workflows, but ensure the token has minimal required permissions
• Automatic merging: Bypasses PR reviews, which is acceptable for automated dependency updates but consider adding validation steps

⚡ Performance Considerations

Efficient Design:

• ✅ Conditional execution prevents unnecessary work when no updates are available
• ✅ Uses --build flag to verify changes before committing
• ✅ Early exit when no changes are detected

Potential Improvements:

1. Build caching: Could benefit from Nix caching strategies for faster builds
2. Frequency: Every 6 hours might be excessive - daily updates could be sufficient
3. Resource usage: The nix-update --build step could be resource-intensive

🧪 Test Coverage & Validation

Positive Aspects:

• ✅ Manual workflow_dispatch trigger for testing
• ✅ Version comparison logic to avoid unnecessary updates
• ✅ Build verification with --build flag

Missing Elements:

• No integration tests: Could benefit from testing in a separate branch first
• No rollback mechanism: If an update breaks something, manual intervention required
• No notification system: Success/failure notifications could be helpful

📋 Specific Recommendations

High Priority Fixes:

# Fix version extraction regex (lines 56, 72, 95)
CURRENT_VERSION=$(grep -o 'version = "[^"]*";' package.nix | head -1 | sed 's/version = "\(.*\)";/\1/')

Medium Priority Improvements:

1. Hardcode branch for scheduled runs:

   - name: Merge branch to master
     run: |
       # For scheduled runs, always merge to master
       TARGET_BRANCH=${{ github.event_name == 'schedule' && 'master' || github.ref_name }}
       git checkout $TARGET_BRANCH

2. Add validation step before merge:

   - name: Validate build
     run: nix build --no-link

Low Priority Enhancements:

1. Consider reducing frequency to daily (0 15 * * *)
2. Add Slack/Discord notifications for update results
3. Add dry-run mode for testing

🎯 Alignment with Repository Guidelines

The workflow aligns well with the project's Nix-based approach and follows the update instructions in CLAUDE.md. The use of nix-update with proper subpackage arguments (tui, node_modules) matches the documented update process.

🏆 Summary

This is a well-engineered automation solution with good error handling and documentation. The main issue is a regex pattern that needs a minor fix to match the actual file format. Once the version extraction is corrected, this workflow should reliably automate OpenCode updates.

Recommendation: ✅ Approve with minor fixes

The workflow demonstrates solid understanding of both GitHub Actions and Nix ecosystem requirements. After fixing the regex pattern, this will provide reliable automated updates for the OpenCode flake.

---