feat: Add support for GitHub Budgets API #3931

youneedgreg · 2026-01-21T01:48:47Z

Pull Request Description: Add Support for GitHub Budgets API

Summary

This PR adds support for the GitHub Budgets REST API, allowing users to programmatically manage budgets for both Organizations and Enterprises. This includes listing, retrieving, creating (Enterprise only), updating, and deleting budgets.

Changes

Data Structures

Added [Budget] and [BudgetAlerting] structs to represent the budget object returned by the API.
Included support for modern fields such as limit_amount, current_amount, and alerting configurations.

Organization Budgets ([BillingService])

Added the following methods to [BillingService]:

[ListOrganizationBudgets]: GET /organizations/{org}/settings/billing/budgets
[GetOrganizationBudget]: GET /organizations/{org}/settings/billing/budgets/{budget_id}
[UpdateOrganizationBudget]: PATCH /organizations/{org}/settings/billing/budgets/{budget_id}
[DeleteOrganizationBudget]: DELETE /organizations/{org}/settings/billing/budgets/{budget_id}

Enterprise Budgets ([EnterpriseService])

Added the following methods to [EnterpriseService]:

[ListEnterpriseBudgets]: GET /enterprises/{enterprise}/settings/billing/budgets
[GetEnterpriseBudget]: GET /enterprises/{enterprise}/settings/billing/budgets/{budget_id}
[CreateEnterpriseBudget]: POST /enterprises/{enterprise}/settings/billing/budgets
[UpdateEnterpriseBudget]: PATCH /enterprises/{enterprise}/settings/billing/budgets/{budget_id}
[DeleteEnterpriseBudget]: DELETE /enterprises/{enterprise}/settings/billing/budgets/{budget_id}

Verification Plan

Automated Tests

Added [github/billing_budgets_test.go] with unit tests for all organization-level methods.
Added [github/enterprise_billing_budgets_test.go] with unit tests for all enterprise-level methods and JSON marshaling validation for the Budget struct.

All tests passed:

go test -v ./github -run 'TestBillingService_.*Budget'
go test -v ./github -run 'TestEnterpriseService_.*Budget'
go test -v ./github -run 'TestBudget_Marshal'

codecov · 2026-01-21T02:15:16Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.48%. Comparing base (4767af9) to head (57e424b).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3931      +/-   ##
==========================================
+ Coverage   92.44%   92.48%   +0.04%     
==========================================
  Files         203      205       +2     
  Lines       14960    15042      +82     
==========================================
+ Hits        13830    13912      +82     
  Misses        927      927              
  Partials      203      203

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

gmlewis

Thank you, @youneedgreg!
Just a few tweaks, please, then we should be ready for a second LGTM+Approval from any other contributor to this repo before merging.

cc: @stevehipwell - @alexandear - @zyfy29 - @Not-Dhananjay-Mishra

github/billing_budgets.go

github/billing_budgets_test.go

github/enterprise_billing_budgets.go

github/billing_budgets.go

github/enterprise_billing_budgets.go

gmlewis · 2026-01-21T02:17:00Z

Also, please fix the linter failures and check the code coverage. Step 4 in CONTRIBUTING.md discusses these things.

Not-Dhananjay-Mishra · 2026-01-21T02:32:44Z

github/billing_budgets.go

+//
+// GitHub API docs: https://docs.github.com/rest/billing/budgets#get-all-budgets-for-an-organization
+//
+// meta:operation GET /organizations/{org}/settings/billing/budgets


For consistency use //meta: (no space).

Suggested change

// meta:operation GET /organizations/{org}/settings/billing/budgets

//meta:operation GET /organizations/{org}/settings/billing/budgets

Same applies to other occurrences in this PR.

Not-Dhananjay-Mishra · 2026-01-21T02:43:24Z

github/billing_budgets.go

+// GitHub API docs: https://docs.github.com/rest/billing/budgets#delete-a-budget-for-an-organization
+//
+// meta:operation DELETE /organizations/{org}/settings/billing/budgets/{budget_id}
+func (s *BillingService) DeleteOrganizationBudget(ctx context.Context, org string, budgetID string) (*Response, error) {


According to Docs this endpoint also returns an object.

Not-Dhananjay-Mishra · 2026-01-21T02:50:42Z

github/enterprise_billing_budgets.go

+
+// GetEnterpriseBudget gets a specific budget for an enterprise.
+//
+// GitHub API docs: https://docs.github.com/rest/billing/budgets#get-a-budget-for-an-enterprise


Suggested change

// GitHub API docs: https://docs.github.com/rest/billing/budgets#get-a-budget-for-an-enterprise

// GitHub API docs: https://docs.github.com/en/enterprise-cloud@latest/rest/billing/budgets#get-a-budget-by-id

https://docs.github.com/en/enterprise-cloud@latest/rest/billing/budgets#get-a-budget-by-id

Not-Dhananjay-Mishra · 2026-01-21T02:51:21Z

github/enterprise_billing_budgets.go

+
+// CreateEnterpriseBudget creates a specific budget for an enterprise.
+//
+// GitHub API docs: https://docs.github.com/rest/billing/budgets#create-a-budget


Suggested change

// GitHub API docs: https://docs.github.com/rest/billing/budgets#create-a-budget

// GitHub API docs: https://docs.github.com/en/enterprise-cloud@latest/rest/billing/budgets#create-a-budget

https://docs.github.com/en/enterprise-cloud@latest/rest/billing/budgets#create-a-budget

Not-Dhananjay-Mishra · 2026-01-21T02:52:04Z

github/enterprise_billing_budgets.go

+
+// UpdateEnterpriseBudget updates a specific budget for an enterprise.
+//
+// GitHub API docs: https://docs.github.com/rest/billing/budgets#update-a-budget-for-an-enterprise


Suggested change

// GitHub API docs: https://docs.github.com/rest/billing/budgets#update-a-budget-for-an-enterprise

// GitHub API docs: https://docs.github.com/en/enterprise-cloud@latest/rest/billing/budgets#update-a-budget

https://docs.github.com/en/enterprise-cloud@latest/rest/billing/budgets#update-a-budget

Not-Dhananjay-Mishra · 2026-01-21T02:52:37Z

github/enterprise_billing_budgets.go

+
+// DeleteEnterpriseBudget deletes a specific budget for an enterprise.
+//
+// GitHub API docs: https://docs.github.com/rest/billing/budgets#delete-a-budget-for-an-enterprise


Suggested change

// GitHub API docs: https://docs.github.com/rest/billing/budgets#delete-a-budget-for-an-enterprise

// GitHub API docs: https://docs.github.com/en/enterprise-cloud@latest/rest/billing/budgets#delete-a-budget

https://docs.github.com/en/enterprise-cloud@latest/rest/billing/budgets#delete-a-budget

Not-Dhananjay-Mishra · 2026-01-21T02:59:00Z

github/enterprise_billing_budgets.go

+
+// ListEnterpriseBudgets lists all budgets for an enterprise.
+//
+// GitHub API docs: https://docs.github.com/rest/billing/budgets#get-all-budgets-for-an-enterprise


Suggested change

// GitHub API docs: https://docs.github.com/rest/billing/budgets#get-all-budgets-for-an-enterprise

// GitHub API docs: https://docs.github.com/en/enterprise-cloud@latest/rest/billing/budgets#get-all-budgets

https://docs.github.com/en/enterprise-cloud@latest/rest/billing/budgets#get-all-budgets

Not-Dhananjay-Mishra · 2026-01-21T03:14:06Z

github/billing_budgets.go

+)
+
+// Budget represents a GitHub budget.
+type Budget struct {


Response schema of Budget

{ "type": "object", "properties": { "id": { "type": "string", "description": "ID of the budget." }, "budget_scope": { "type": "string", "description": "The type of scope for the budget", "enum": [ "enterprise", "organization", "repository", "cost_center" ], "examples": [ "enterprise" ] }, "budget_entity_name": { "type": "string", "description": "The name of the entity to apply the budget to", "examples": [ "octocat/hello-world" ] }, "budget_amount": { "type": "integer", "description": "The budget amount in whole dollars. For license-based products, this represents the number of licenses." }, "prevent_further_usage": { "type": "boolean", "description": "Whether to prevent additional spending once the budget is exceeded", "examples": [ true ] }, "budget_product_sku": { "type": "string", "description": "A single product or sku to apply the budget to.", "examples": [ "actions_linux" ] }, "budget_type": { "type": "string", "description": "The type of pricing for the budget", "enum": [ "ProductPricing", "SkuPricing" ], "examples": [ "ProductPricing" ] }, "budget_alerting": { "type": "object", "properties": { "will_alert": { "type": "boolean", "description": "Whether alerts are enabled for this budget", "examples": [ true ] }, "alert_recipients": { "type": "array", "items": { "type": "string" }, "description": "Array of user login names who will receive alerts", "examples": [ "mona", "lisa" ] } } } }, "required": [ "id", "budget_amount", "prevent_further_usage", "budget_product_sku", "budget_type", "budget_alerting", "budget_scope", "budget_entity_name" ] }

it has few missing items -
budget_scope, budget_entity_name, budget_amount, prevent_further_usage, budget_product_sku.

Not-Dhananjay-Mishra · 2026-01-21T03:15:34Z

github/enterprise_billing_budgets.go

+// GitHub API docs: https://docs.github.com/rest/billing/budgets#delete-a-budget-for-an-enterprise
+//
+// meta:operation DELETE /enterprises/{enterprise}/settings/billing/budgets/{budget_id}
+func (s *EnterpriseService) DeleteEnterpriseBudget(ctx context.Context, enterprise string, budgetID string) (*Response, error) {


It also returns an object

youneedgreg · 2026-01-21T04:02:28Z

Hi @gmlewis , finished and made sure all checks passed, Thank you.

alexandear · 2026-01-21T11:20:41Z

github/enterprise_billing_budgets.go

+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/billing/budgets#get-all-budgets
+//
+//meta:operation GET /enterprises/{enterprise}/settings/billing/budgets
+func (s *EnterpriseService) ListEnterpriseBudgets(ctx context.Context, enterprise string) ([]*Budget, *Response, error) {


Since we call this in Enterprise service we can simplify naming:

Suggested change

func (s *EnterpriseService) ListEnterpriseBudgets(ctx context.Context, enterprise string) ([]*Budget, *Response, error) {

func (s *EnterpriseService) ListBudgets(ctx context.Context, enterprise string) ([]*Budget, *Response, error) {

Am I missing something?

Not-Dhananjay-Mishra · 2026-01-21T13:10:44Z

github/billing_budgets.go

+// GitHub API docs: https://docs.github.com/rest/billing/budgets#get-all-budgets-for-an-organization
+//
+//meta:operation GET /organizations/{org}/settings/billing/budgets
+func (s *BillingService) ListOrganizationBudgets(ctx context.Context, org string) ([]*Budget, *Response, error) {


This endpoint returns a response with the following shape:

{ "budgets": [ { "id": "2066deda-923f-43f9-88d2-62395a28c0cdd", "budget_type": "ProductPricing", "budget_product_skus": [ "actions" ], "budget_scope": "enterprise", "budget_amount": 1000, "prevent_further_usage": true, "budget_alerting": { "will_alert": true, "alert_recipients": [ "enterprise-admin", "billing-manager" ] } }, { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "budget_type": "SkuPricing", "budget_product_skus": [ "actions_linux" ], "budget_scope": "organization", "budget_amount": 500, "prevent_further_usage": false, "budget_alerting": { "will_alert": true, "alert_recipients": [ "org-owner" ] } } ], "has_next_page": false }

I believe it should return a struct like

{ Budgets []Budget `json:"budgets"` HasNextPage bool `json:"has_next_page,omitempty"` }

Not-Dhananjay-Mishra · 2026-01-21T13:14:55Z

github/billing_budgets.go

+// GitHub API docs: https://docs.github.com/rest/billing/budgets#update-a-budget-for-an-organization
+//
+//meta:operation PATCH /organizations/{org}/settings/billing/budgets/{budget_id}
+func (s *BillingService) UpdateOrganizationBudget(ctx context.Context, org, budgetID string, budget *Budget) (*Budget, *Response, error) {


This endpoint returns a response with the following shape:

{ "message": "Budget successfully updated.", "budget": { "id": "2066deda-923f-43f9-88d2-62395a28c0cdd", "budget_type": "SkuPricing", "budget_product_sku": "actions", "budget_scope": "enterprise", "budget_amount": 500, "prevent_further_usage": true, "budget_alerting": { "will_alert": true, "alert_recipients": ["mona"] } } }

I believe it should return a struct like

{ Budget Budget `json:"budget"` Message string `json:"message"` }

Not-Dhananjay-Mishra · 2026-01-21T13:19:16Z

github/enterprise_billing_budgets.go

+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/billing/budgets#get-all-budgets
+//
+//meta:operation GET /enterprises/{enterprise}/settings/billing/budgets
+func (s *EnterpriseService) ListBudgets(ctx context.Context, enterprise string) ([]*Budget, *Response, error) {


same as comment

Not-Dhananjay-Mishra · 2026-01-21T13:20:47Z

github/enterprise_billing_budgets.go

+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/billing/budgets#create-a-budget
+//
+//meta:operation POST /enterprises/{enterprise}/settings/billing/budgets
+func (s *EnterpriseService) CreateBudget(ctx context.Context, enterprise string, budget *Budget) (*Budget, *Response, error) {


same as comment

Not-Dhananjay-Mishra · 2026-01-21T13:21:22Z

github/enterprise_billing_budgets.go

+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/billing/budgets#update-a-budget
+//
+//meta:operation PATCH /enterprises/{enterprise}/settings/billing/budgets/{budget_id}
+func (s *EnterpriseService) UpdateBudget(ctx context.Context, enterprise, budgetID string, budget *Budget) (*Budget, *Response, error) {


same as comment

feat: add support for GitHub Budgets API

3af8d69

gmlewis changed the title ~~feat: add support for GitHub Budgets API~~ feat: Add support for GitHub Budgets API Jan 21, 2026

gmlewis requested changes Jan 21, 2026

View reviewed changes

youneedgreg added 2 commits January 21, 2026 05:53

chore: address PR google#3931 review comments

d18bb71

test: add error path tests for 100% coverage

bf47de7

Not-Dhananjay-Mishra reviewed Jan 21, 2026

View reviewed changes

chore: update generated files

0e911d0

alexandear reviewed Jan 21, 2026

View reviewed changes

chore: address PR google#3931 review comments

57e424b

Not-Dhananjay-Mishra reviewed Jan 21, 2026

View reviewed changes

	// meta:operation GET /organizations/{org}/settings/billing/budgets
	//meta:operation GET /organizations/{org}/settings/billing/budgets

	// GitHub API docs: https://docs.github.com/rest/billing/budgets#get-a-budget-for-an-enterprise
	// GitHub API docs: https://docs.github.com/en/enterprise-cloud@latest/rest/billing/budgets#get-a-budget-by-id

	func (s EnterpriseService) ListEnterpriseBudgets(ctx context.Context, enterprise string) ([]Budget, *Response, error) {
	func (s EnterpriseService) ListBudgets(ctx context.Context, enterprise string) ([]Budget, *Response, error) {

feat: Add support for GitHub Budgets API #3931

Are you sure you want to change the base?

feat: Add support for GitHub Budgets API #3931

Conversation

youneedgreg commented Jan 21, 2026

Pull Request Description: Add Support for GitHub Budgets API

Summary

Changes

Data Structures

Organization Budgets ([BillingService])

Enterprise Budgets ([EnterpriseService])

Verification Plan

Automated Tests

Uh oh!

codecov bot commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

gmlewis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gmlewis commented Jan 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Not-Dhananjay-Mishra Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

youneedgreg commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Not-Dhananjay-Mishra Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Not-Dhananjay-Mishra Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Not-Dhananjay-Mishra Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

codecov bot commented Jan 21, 2026 •

edited

Loading

Not-Dhananjay-Mishra Jan 21, 2026 •

edited

Loading

youneedgreg commented Jan 21, 2026 •

edited

Loading

Not-Dhananjay-Mishra Jan 21, 2026 •

edited

Loading

Not-Dhananjay-Mishra Jan 21, 2026 •

edited

Loading

Not-Dhananjay-Mishra Jan 21, 2026 •

edited

Loading