org_budgets

Creates, updates, deletes, gets or lists an org_budgets resource.

Overview

Name	org_budgets
Type	Resource
Id	github.billing.org_budgets

Fields

The following fields are returned by SELECT queries:

get_budget_org

Response when updating a budget

Name	Datatype	Description
id	string	ID of the budget.
budget_entity_name	string	The name of the entity to apply the budget to (example: octocat/hello-world)
budget_alerting	object
budget_amount	integer	The budget amount in whole dollars. For license-based products, this represents the number of licenses.
budget_product_sku	string	A single product or sku to apply the budget to. (example: actions_linux)
budget_scope	string	The type of scope for the budget (enterprise, organization, repository, cost_center, multi_user_customer, multi_user_cost_center, user) (example: enterprise)
budget_type	string	The type of pricing for the budget (ProductPricing) (example: ProductPricing)
prevent_further_usage	boolean	Whether to prevent additional spending once the budget is exceeded
user	string	The user login when the budget is scoped to a single user (user scope). (example: octocat)

get_all_budgets_org

Response when getting all budgets

Name	Datatype	Description
budgets	array	Array of budget objects for the enterprise
effective_budget	object	Effective user-level budget details returned when the response is scoped with the user query parameter.
has_next_page	boolean	Indicates if there are more pages of results available (maps to hasNextPage from billing platform)
total_count	integer	Total number of budgets matching the query
user	string	User login included when the response is scoped with the user query parameter.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_budget_org	select	org, budget_id		Gets a budget by ID. The authenticated user must be an organization admin or billing manager.
get_all_budgets_org	select	org	page, per_page, scope, user	Gets all budgets for an organization. The authenticated user must be an organization admin or billing manager. Each page returns up to 100 budgets.
create_organization_budget	insert	org		Creates a new budget for an organization. The authenticated user must be an organization admin or billing manager.
update_budget_org	update	org, budget_id		Updates an existing budget for an organization. The authenticated user must be an organization admin or billing manager.
delete_budget_org	delete	org, budget_id		Deletes a budget by ID for an organization. The authenticated user must be an organization admin or billing manager.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
budget_id	string	The ID corresponding to the budget.
org	string	The organization name. The name is not case sensitive.
page	integer	The page number of the results to fetch.
per_page	integer	The number of results per page (max 100).
scope	string	Filter budgets by scope type. - organization: Budgets scoped to the organization. - repository: Budgets scoped to a repository. - multi_user_customer: Universal budgets that apply to all users in the organization. - user: Budgets scoped to an individual user.
user	string	Filter consumed amount details for budgets by the specified user login.

SELECT examples

get_budget_org

Gets a budget by ID. The authenticated user must be an organization admin or billing manager.

SELECT
id,
budget_entity_name,
budget_alerting,
budget_amount,
budget_product_sku,
budget_scope,
budget_type,
prevent_further_usage,
user
FROM github.billing.org_budgets
WHERE org = '{{ org }}' -- required
AND budget_id = '{{ budget_id }}' -- required
;

get_all_budgets_org

Gets all budgets for an organization. The authenticated user must be an organization admin or billing manager.
Each page returns up to 100 budgets.

SELECT
budgets,
effective_budget,
has_next_page,
total_count,
user
FROM github.billing.org_budgets
WHERE org = '{{ org }}' -- required
AND page = '{{ page }}'
AND per_page = '{{ per_page }}'
AND scope = '{{ scope }}'
AND user = '{{ user }}'
;

INSERT examples

create_organization_budget

Creates a new budget for an organization. The authenticated user must be an
organization admin or billing manager.

INSERT INTO github.billing.org_budgets (
budget_amount,
prevent_further_usage,
budget_alerting,
budget_scope,
budget_entity_name,
budget_type,
budget_product_sku,
user,
org
)
SELECT 
{{ budget_amount }},
{{ prevent_further_usage }},
'{{ budget_alerting }}',
'{{ budget_scope }}',
'{{ budget_entity_name }}',
'{{ budget_type }}',
'{{ budget_product_sku }}',
'{{ user }}',
'{{ org }}'
RETURNING
budget,
message
;

Manifest

# Description fields are for documentation purposes
- name: org_budgets
props:
  - name: org
    value: "{{ org }}"
    description: Required parameter for the org_budgets resource.
  - name: budget_amount
    value: {{ budget_amount }}
    description: |
      The budget amount in whole dollars. For license-based products, this represents the number of licenses.
  - name: prevent_further_usage
    value: {{ prevent_further_usage }}
    description: |
      Whether to prevent additional spending once the budget is exceeded. For `user` and `multi_user_customer` scopes, this must be `true`.
  - name: budget_alerting
    value:
      will_alert: {{ will_alert }}
      alert_recipients:
        - "{{ alert_recipients }}"
  - name: budget_scope
    value: "{{ budget_scope }}"
    description: |
      The scope of the budget for this organization.
      - `organization`: Apply the budget to the organization.
      - `repository`: Apply the budget to a specific repository in the organization.
      - `multi_user_customer`: Apply a universal budget to all users in the organization.
      - `user`: Apply the budget to a single user in the organization.
      `user` and `multi_user_customer` scopes are only supported when
      `budget_product_sku` is `ai_credits` or `premium_requests`.
    valid_values: ['organization', 'repository', 'multi_user_customer', 'user']
  - name: budget_entity_name
    value: "{{ budget_entity_name }}"
    description: |
      The name of the entity to apply the budget to
    default: 
  - name: budget_type
    value: "{{ budget_type }}"
    description: |
      The type of pricing model used by the budget. Determines how `budget_product_sku` is interpreted.
      - `BundlePricing`: Covers all AI credit SKUs. Set `budget_product_sku` to `ai_credits`.
      - `ProductPricing`: Covers all SKUs that belong to a product. Set `budget_product_sku` to a product such as `actions` or `packages`.
      - `SkuPricing`: Covers a single, specific SKU. Set `budget_product_sku` to a SKU such as `actions_linux`.
    valid_values: ['BundlePricing']
  - name: budget_product_sku
    value: "{{ budget_product_sku }}"
    description: |
      A single product or SKU that will be covered in the budget
  - name: user
    value: "{{ user }}"
    description: |
      The username of the user for `user` scope budgets. This field is required when `budget_scope` is `user`.

UPDATE examples

update_budget_org

Updates an existing budget for an organization. The authenticated user must be an organization admin or billing manager.

UPDATE github.billing.org_budgets
SET 
budget_amount = {{ budget_amount }},
prevent_further_usage = {{ prevent_further_usage }},
budget_alerting = '{{ budget_alerting }}',
budget_scope = '{{ budget_scope }}',
budget_entity_name = '{{ budget_entity_name }}',
budget_type = '{{ budget_type }}',
budget_product_sku = '{{ budget_product_sku }}',
user = '{{ user }}'
WHERE 
org = '{{ org }}' --required
AND budget_id = '{{ budget_id }}' --required
RETURNING
budget,
message;

DELETE examples

delete_budget_org

Deletes a budget by ID for an organization. The authenticated user must be an organization admin or billing manager.

DELETE FROM github.billing.org_budgets
WHERE org = '{{ org }}' --required
AND budget_id = '{{ budget_id }}' --required
;