Gate CI on budget

A pipeline step that runs solwyn budget status --max-utilization <percent> prints the project's budget and exits 4 when utilization is at or above the threshold. Nothing else is needed: no SDK, no code change, no webhook. The status still prints, so the job log shows why the step stopped.

What you need

• The CLI installed on the runner. See Installation.
• A project key in the SOLWYN_API_KEY environment variable. A read-only key is enough, because the gate only reads. See Key scopes.
• The project ID, passed as --project or as SOLWYN_PROJECT_ID.

The step

# Fail the job when the project is at or over 80% of its monthly budget.
solwyn --project "$SOLWYN_PROJECT_ID" --json budget status --max-utilization 80

Exit codes are frozen, so branch on them directly:

The --json flag goes before the subcommand. The payload lands on stdout under the solwyn.budget-status.v1 schema, and any error lands on stderr under solwyn.error.v1, so a later step can parse the numbers without scraping the table.

GitHub Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pipx install solwyn-cli
      - name: Budget gate
        env:
          SOLWYN_API_KEY: ${{ secrets.SOLWYN_READ_ONLY_KEY }}
          SOLWYN_PROJECT_ID: ${{ vars.SOLWYN_PROJECT_ID }}
        run: solwyn --json budget status --max-utilization 80
      - name: Deploy
        run: ./deploy.sh

Because budget status is a pure read, running it on every job is safe. It never reserves budget and never counts as spend.

Choosing a threshold

The gate compares against the project's utilization, the share of the monthly limit already used. A threshold of 80 leaves headroom for the deploy itself and for alert delivery. If the project uses hard_deny mode, calls are already refused at 100 percent, so the gate's job is to stop a rollout before production hits that wall. In alert_only mode the gate is the only thing that stops spend automatically, so pick the number you would want a human to act on.

Gating on a forecast instead

To block on where spend is heading rather than where it is, read solwyn forecast with --json and compare its projected month-end figure in the pipeline. The gate above is simpler and covers most cases; reach for the forecast when a project's spend is bursty enough that current utilization understates the risk.

See also

• Scripting and CI — the full machine contract: envelope, exit codes, retries.
• Metering un-instrumented calls — when the pipeline itself makes provider calls and should reserve budget for them.
• budget status — the command reference.