Shared Budget Updater

A sheet-driven budget pusher for Google Ads. You (or your pacing process) drop approved changes into a Google Sheet tab — customer ID, shared budget ID, new amount. A daily GitHub Actions cron pushes each row to Google Ads and marks it done. This tool CHANGES live budgets — the sheet is the approval gate, so control who can edit the sheet.

Why this exists

Budget pacing produces a daily list of "set budget X to $Y" decisions. Doing them by hand in the Ads UI is slow and error-prone at portfolio scale; doing them with ad-hoc scripts scatters mutation code everywhere. This gives the decision list one narrow, auditable exit: a sheet row in, one campaignBudgets:mutate (amount only) out, column D as the receipt.

Pairs with Budget Guardian — the tripwire that watches MTD spend against monthly budgets. This skill pushes the budgets; the Guardian catches anything that then overspends them.

Architecture

GitHub Actions (daily cron)
        |
        v
  Read uploader tab      ----->  Google Sheets API
  (rows where col D empty)       (your approved changes)
        |
        v
  For each row:
    amount <= $0?  -- yes -->  skip + alert (never reaches the API)
        |
        v
    campaignBudgets:mutate  -->  Google Ads API (REST)
    (updateMask: amount_micros)
        |
   ok?  +-- yes -->  mark col D "x"   -->  Google Sheets API
        |
        +-- no  -->  leave col D empty (retries next run)
                        |
                        v
             one consolidated Slack alert for all failed rows

When Claude should invoke this skill

• User asks to "set up shared budget updater" or "deploy the budget updater"
• User wants to push budget changes from a spreadsheet on a schedule
• User asks to bulk-update shared budgets across accounts from a sheet
• User describes a pacing workflow that ends in manual budget edits and wants the execution automated behind a sheet-approval gate

How Claude helps the user deploy this

1. Confirm prerequisites (Google Ads API access, Google Sheets OAuth token, Slack webhook, GitHub repo for the cron)
2. Walk through README.md setup — copying files, creating the sheet tab per sheet-template.md, setting GitHub secrets
3. Emphasize the safety model: whoever can edit the sheet can change spend — lock sheet sharing down before wiring credentials
4. Run the manual test from README Step 6 (one row, the user's OWN test account, $1 change, verify in Ads, revert)
5. Confirm the daily cron is firing in the Actions tab
6. For alert triage after deployment: rules.md (decision table) and examples.md (worked decisions)

When a row fails — where it routes

Triage itself lives in rules.md (read it before acting on any failed row; examples.md shows worked reads). What triage surfaces routes to siblings:

Files in this skill

Configuration

All identity-bearing values are loaded from environment variables — nothing is hardcoded. The full env-var table, including which missing values crash the run and which quietly degrade it, lives in references/update-contract.md; README.md Step 5 maps each one to a GitHub Actions secret.

Tested against

• Google Ads API v23 (REST)
• Python 3.12
• GitHub Actions (Ubuntu)
• Slack incoming webhooks (Block Kit)
• Google Sheets API v4 with OAuth user credentials

What this skill deliberately does NOT do

• No dry-run or approval prompt. The sheet IS the approval surface — a row with column D empty is an approved change. Secure sheet access accordingly; that is the entire access model.
• Never touches anything but the budget amount. The mutation is campaignBudgets:mutate with updateMask: amount_micros. No statuses, no bidding, no campaign fields — and it should stay that way.
• Exits 0 on partial failure by design. Failed rows keep an empty column D and retry on the next run; the consolidated Slack alert is the failure signal. The yml failure() alert only fires on crashes.
• No LLM in the loop. Pure read-transform-mutate; Claude helps you deploy and triage, never executes budget changes itself.

Production twins & behavior parity

This bundle is the generic replica of two production installs of the same architecture (two separate account books, one codebase pattern). The copies stay in behavioral sync on the parity set — the exact set, and the by-design divergences (env names + sheet wiring, Slack branding, fallback mention), are defined in references/update-contract.md § Parity with the production twins. Drift between the copies is reviewed against that set, never byte-synced.