GHCP-ULB-Sync

GitHub Copilot User-Level Budget Sync — manage enterprise AI Credits user budgets from a local CSV that you edit like a config file.

It works like git: a local file (ai-credits-budgets.csv) is your source of truth. The first run creates that file from GitHub. You edit the amounts, run sync, and only the rows you changed are pushed. A local baseline records the last-synced state so the tool knows exactly what you edited — without re-reading all of GitHub every time.

One-time setup: clone the repo and install (see Install), then:

Copy the example file and fill in your two values:

cp .env.example .env

# .env
GITHUB_TOKEN=ghp_your_personal_access_token        # classic PAT scope: manage_billing:enterprise
GITHUB_ENTERPRISE=your-enterprise-slug             # the part in https://github.com/enterprises/<slug>

ghcp_ulb_sync

• First run: if ai-credits-budgets.csv doesn't exist yet, this creates it from your current GitHub budgets and stops — edit it, then run the command again.
• Every run after that: it shows a diff of just your edits, asks you to confirm, and pushes only the changed rows.

Prefer not to use .env? Pass the values on the command line instead: python -m ghcp_ulb_sync --enterprise your-slug --token ghp_xxx.

# 1. First run — creates ./ai-credits-budgets.csv from current GitHub budgets, then stops.
ghcp-ulb-sync --enterprise my-ent

# 2. Edit the file — change the budget_amount values, add or remove users.
$EDITOR ai-credits-budgets.csv

# 3. Sync — shows a diff of just your edits, asks to confirm, and pushes them.
ghcp-ulb-sync --enterprise my-ent

From then on: edit the file whenever budgets change, run sync, repeat. You can run sync as often as you like — if nothing changed, it does nothing.

sync compares the current CSV against the last-synced local copy (the baseline stored in .ghcp-ulb-sync/), and pushes only the differences:

After a successful push, the baseline is updated to match your file. This makes normal runs cheap — no full GitHub re-read; only the handful of edited rows are pushed.

Trade-off: because the diff is against your local baseline, budgets changed directly on GitHub (e.g. in the UI, outside this tool) are not auto-detected. Run ghcp-ulb-sync --pull whenever you want to refresh the file and baseline from GitHub.

• Python 3.9+
• A GitHub token for an enterprise admin or billing manager (classic PAT scope: manage_billing:enterprise).
• Your enterprise slug — the part in https://github.com/enterprises/<slug>.

git clone https://github.com/abhi-singhs/GHCP-ULB-Sync.git
cd GHCP-ULB-Sync

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -e .                   # installs the `ghcp-ulb-sync` command

Provide the token and enterprise slug however is most convenient (precedence: CLI flag > environment variable > .env file):

cp .env.example .env
# then edit .env:
#   GITHUB_TOKEN=ghp_xxx
#   GITHUB_ENTERPRISE=my-enterprise-slug

With those set you can drop the --enterprise/--token flags entirely:

ghcp-ulb-sync            # uses GITHUB_TOKEN / GITHUB_ENTERPRISE

A header row plus one row per user — exactly two columns:

user_login,budget_amount
hubot,25
mona-lisa,100
octocat,50

• user_login — the user's GitHub login.
• budget_amount — whole dollars (integer). $ and thousands separators are tolerated (e.g. "$1,200"); fractional amounts are rejected.

The file is generated for you on the first run; samples/budgets.csv shows the format. Commit ai-credits-budgets.csv to your repo — it's your source of truth.

ghcp-ulb-sync                       # sync: create on first run, else push your edits
ghcp-ulb-sync --dry-run             # show what would be pushed, push nothing
ghcp-ulb-sync --yes                 # push without the confirmation prompt (CI)
ghcp-ulb-sync --pull                # re-create the CSV + baseline from GitHub (--force to skip confirm)

Loaded 3 user(s) from ai-credits-budgets.csv.

        Edits to push — my-ent
┏━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━┓
┃ User    ┃ Last synced ┃ New ┃ Action ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━╇━━━━━━━━┩
│ newhire │           — │ $20 │ CREATE │
│ octocat │         $50 │ $75 │ UPDATE │
└─────────┴─────────────┴─────┴────────┘

Summary: 1 to create, 1 to update (2 change(s) total).
Push 2 change(s) now? [y/N]:

Exit codes: 0 success / nothing to do · 1 one or more pushes failed · 2 configuration or CSV error.

Under --state-dir (default ./.ghcp-ulb-sync/, git-ignored):

• snapshot.json — the last-synced local copy: per enterprise, each user's {amount, budget_id}. This is what the next sync diffs your CSV against.

• audit-log.jsonl — one JSON line per change, appended as it happens:

  {"timestamp":"...","enterprise":"my-ent","user_login":"octocat","action":"update","old_amount":50,"new_amount":75,"result":"success"}

The audit log is written incrementally and the baseline is checkpointed during a run, so an interrupted sync stays accurate and is safe to re-run. A failed push keeps its old baseline value so the change is retried next time.

The root ai-credits-budgets.csv is your editable state (commit it). The .ghcp-ulb-sync/ baseline is machine-local by default.

Because normal sync diffs against the local baseline, a steady-state run makes no GitHub reads — it only issues writes (PATCH/POST) for the rows you actually edited. So pushing 5 edits is 5 requests, regardless of how many thousands of users you manage.

The request-heavy operations are the ones that must read all of GitHub — the first bootstrap and any --pull — because the list endpoint returns at most 10 budgets per page (≈ N/10 GETs, e.g. ~500 for 5,000 users). These show a progress indicator and:

• Handle rate limits automatically — primary limits (X-RateLimit-Remaining: 0) and secondary/abuse limits (403/429) are detected; the tool waits (Retry-After/reset) and resumes. Genuine permission 403s still fail fast.
• Are serial by design — GitHub advises against concurrent writes (secondary limits).
• Are crash-safe — incremental audit log + checkpointed baseline.

The plan table is truncated to the first 50 changes (with an "…and N more" note); the full set is always pushed and recorded in the audit log.

Endpoints used (API version 2026-03-10):

• GET /enterprises/{enterprise}/settings/billing/budgets?scope=user (paginated) — list (used on bootstrap / --pull).
• POST /enterprises/{enterprise}/settings/billing/budgets — create a user budget (budget_scope: user, budget_product_sku: ai_credits, budget_type: ProductPricing, prevent_further_usage: true).
• PATCH /enterprises/{enterprise}/settings/billing/budgets/{id} — update the amount.

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

pip install -e ".[dev]"
pytest                # run the test suite (no network calls)
python -m ghcp_ulb_sync --help

MIT.