SOLWYN

Gate CI on budget

Block a deploy or a scheduled job when a project is at or near its budget cap, using one CLI command and one exit code

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.
  • An API key in the SOLWYN_API_KEY environment variable. A read-only key is enough, because the gate only reads. See Key scopes.
  • The project, as SOLWYN_PROJECT or --project: a name or proj_ id.

The step

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

Exit codes are frozen, so branch on them directly:

ExitMeaningWhat the pipeline should do
0Utilization is below the threshold.Continue.
4Utilization is at or above the threshold.Stop. The project is near its cap.
3No usable credential.Fix the runner's secret.
2 or 5The project was not found, or the key doesn't reach it (project_not_found).Fix SOLWYN_PROJECT, or use a key for that project.
1Network or API failure.Decide locally: retry, or fail open and continue.

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

.github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pipx install 'solwyn-cli>=0.5.1'
      - name: Budget gate
        env:
          SOLWYN_API_KEY: ${{ secrets.SOLWYN_READ_ONLY_KEY }}
          SOLWYN_PROJECT: ${{ vars.SOLWYN_PROJECT }}
        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

On this page