feat(ci): add reusable actions budget guard workflow

[LucasSantana-Dev]

Summary

• add reusable budget guard workflow for GitHub Actions minutes usage
• compute current UTC month usage from org billing usage endpoint
• expose usage_pct, warn_mode, degrade_mode, and summary outputs
• default thresholds to 70/85 and fail-open when billing lookup fails

Validation

• bash -n .github/scripts/actions-budget-guard.sh
• .github/scripts/tests/actions-budget-guard.test.sh
• workflow YAML parse check

Summary by CodeRabbit

Release Notes

• New Features

  • Added a reusable GitHub Actions budget guard workflow to monitor and enforce monthly Actions usage limits with configurable warning and degradation thresholds.

• Tests

  • Introduced comprehensive test suite validating usage monitoring across multiple scenarios (below warning, warning-only, degradation, and error handling).

• Documentation

  • Updated project documentation with details on the new budget guard workflow for limit-aware CI orchestration.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces a GitHub Actions budget guard system that monitors organizational GitHub Actions usage against configured spending caps. It includes a Bash script for usage evaluation, a test suite with multiple scenarios, two GitHub Actions workflows (one reusable, one for testing), and documentation updates to reflect the new capabilities.

Changes

Cohort / File(s)	Summary
Budget Guard Implementation .github/scripts/actions-budget-guard.sh	Core script with input validation, helper functions, usage data source selection (mock file, forced failure, or live GitHub API call), JSON parsing of billing data, percentage computation, and structured output emission. Implements fail-open semantics with proper error handling.
Testing Infrastructure .github/scripts/tests/actions-budget-guard.test.sh, .github/scripts/tests/fixtures/*	Test script with assertion helpers and test runners; three JSON fixture files (usage-below-warn.json, usage-warn-only.json, usage-degrade.json) representing different usage scenarios at 10%, 75%, and 90% of monthly cap respectively.
Workflow Automation .github/workflows/reusable-actions-budget-guard.yml, .github/workflows/test-actions-budget-guard.yml	Reusable workflow that resolves source repo, checks out code, executes budget guard script with inputs, and publishes summary outputs; test workflow that runs on PR/push to main with shell syntax validation and test execution.
Documentation CHANGELOG.md, README.md	Changelog entry documenting new reusable workflow, script, and test workflow; README infrastructure note indicating budget guard availability for new org/project bootstraps.

Sequence Diagram

sequenceDiagram
    participant WF as GitHub Actions Workflow
    participant Script as Budget Guard Script
    participant API as GitHub Billing API
    participant Output as Workflow Outputs

    WF->>WF: Resolve workflow source & checkout
    WF->>Script: Execute with ORG, MONTHLY_CAP_MINUTES, token
    
    alt Mock Data Available
        Script->>Script: Load usage from mock JSON file
    else API Failure Forced
        Script->>Script: Simulate API error
    else Live Query
        Script->>API: GET /orgs/{org}/billing/actions<br/>(with GitHub token)
        API-->>Script: Usage JSON payload
    end
    
    Script->>Script: Parse JSON, extract current month minutes
    Script->>Script: Compute usage_pct, warn_mode, degrade_mode
    Script->>Output: Emit structured outputs<br/>(usage_pct, warn_mode, degrade_mode, summary)
    
    WF->>WF: Append summary to job summary
    Output-->>WF: Return outputs to caller

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A guard so wise for Actions' gold,
Prevents the budget from growing cold,
With tests in place and fixtures neat,
The CI pipeline stays fleet,
Now organizations count their spend with glee! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat(ci): add reusable actions budget guard workflow' accurately and concisely summarizes the main change—introducing a new reusable workflow for managing GitHub Actions budget.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/actions-budget-guard

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}