Gradual rollouts

Release to a growing share of users and roll back automatically when metrics drop.

A gradual rollout serves a new variation to a percentage of users and increases it over time. If something breaks, only a small slice of traffic sees it.

Start internal

Target the Internal staff segment with on and the default rule with off. Use it for a day.
Open to 5%

Change the default rule to a percentage rollout: on 5%, off 95%.
Terminal
```
npx shoal rollout new-checkout --env production --percent 5
```

Schedule the ramp

Let Shoal increase the percentage on a schedule:

Terminal

npx shoal rollout new-checkout --env production \
  --schedule "5%:now, 25%:+1d, 50%:+3d, 100%:+7d"

Watch and finish

At 100%, leave it for a week, then delete the flag and the old code path.

Guarded rollouts

Connect a metric — error rate, p95 latency, conversion — and Shoal pauses or reverses the rollout when it crosses a threshold.

shoal.yaml

flags:
  new-checkout:
    rollout:
      schedule: ["5%:now", "25%:+1d", "100%:+7d"]
      guard:
        metric: checkout_error_rate
        max: 0.02
        action: rollback