GitHub environment reviewers: approve before a paid Sume run

To make a GitHub Actions workflow wait for a human before it spends money on Sume, store the Sume API key as a secret of a GitHub environment that has required reviewers, and point the paid job at that environment. GitHub holds the job until a reviewer approves, and the secret is not handed to the job before then. Add a per-run generation_spend_cap_usd to the request and the approval gate has a hard dollar ceiling behind it.

The GitHub facts come from Managing environments for deployment and Reviewing deployments, both read on 2026-10-10. The Sume facts come from Create a run and Runs and results.

What does the environment gate actually do?

GitHub's environment page says an environment can require up to 6 people or teams as reviewers, and only one of them needs to approve for the job to proceed. It also says secrets stored on an environment are only available to jobs that use that environment, and only after the configured rules pass. That second sentence is the useful one for a paid API: a job that references a different environment, or none, never sees the Sume key.

There is an optional setting to prevent self-approval. With it on, the person who triggered the run cannot approve their own deployment, which turns the gate into a real second pair of eyes instead of a click-through.

How do I wire the workflow?

Create an environment called sume-paid, add reviewers, and put SUME_API_KEY in that environment rather than at repository level. Then reference it from the one job that calls Sume. Everything before the approval, such as linting a brief or validating inputs, can run in an earlier job that has no key.

The request below starts a Format run with a spend cap and an idempotency key built from the workflow run id. A re-run of the same workflow keeps the run id, so Sume replays the original run (200 with idempotency_hit: true) instead of billing a second one.

jobs:
  render:
    runs-on: ubuntu-latest
    environment: sume-paid
    steps:
      - name: Start the Format run
        env:
          SUME_API_KEY: ${{ secrets.SUME_API_KEY }}
        run: |
          curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
            -H "Authorization: Bearer $SUME_API_KEY" \
            -H "Content-Type: application/json" \
            -H "Idempotency-Key: gh-${{ github.run_id }}" \
            -d '{"instruction":"Make the promo for the SKU in input.","input":{"sku":"A-100"},"generation_spend_cap_usd":20}'

Why add a spend cap if a person already approved?

Approval answers "should this start", not "how much may it spend". Sume's Create a run page says every Format has a generation spend cap, and a run can never spend more than its own effective cap. If you send nothing the run uses the Format's cap, a Format that never named one reports the platform default of $400, and a number above the Format's own cap is accepted and not clamped. You can send any number up to 500; 0 or anything above 500 is a 400.

So the reviewer approves a bounded action. Pick a cap that matches what the reviewer expects to see, and put that number in the workflow file where the reviewer can read it on the approval screen. The receipt then reports usage.generation_spend_cap_usd_micros and usage.billable_amount_usd_micros, so the run summary can print spend against the cap.

What should the job do after it starts the run?

Do not hold the approved job open for a long render. The Runs and results page says long-form video can be 15 to 30 minutes of work, and a non-terminal receipt carries expires_at, the deadline after which Sume force-finalizes the run as failed (90 minutes from creation, or earlier for a silent run). Store data.id, then either poll status_url with backoff or send communication.webhook_url so Sume tells your receiver when the run ends.

If the reviewer rejects the deployment, the job never starts and nothing is submitted. If the job is approved and later canceled, a Format run can be stopped with POST /v1/format-runs/{run_id}/cancel, and you pay for the generation completed before the cancel.

• Environment secrets keep the key away from pull-request workflows.
• One idempotency key per workflow run keeps a re-run from billing twice.
• A cap in the request body is the part the reviewer can audit.