Bitbucket Pipelines step cancellation: missing configurable grace period

Direct answer

Bitbucket Pipelines does not expose a configurable grace period between SIGTERM and SIGKILL, nor does it provide a pre-stop hook or signal-trap registration point. When a step is cancelled or exceeds its timeout, the runner sends SIGTERM and then SIGKILL after a fixed interval of roughly 10 seconds. There is no documented YAML key, environment variable, repository setting, or REST API field to change that interval or to register cleanup logic that Bitbucket invokes before termination.

Confirmed behavior versus inferred details

The fixed SIGTERM → SIGKILL sequence and the absence of a configurable grace period are consistent with the documented runner behavior. What is not explicitly documented is a machine-readable label for the terminating signal. The step log records an exit code—143 for SIGTERM and 137 for SIGKILL—but this follows the standard Unix convention rather than a Bitbucket-specific field. The REST API for pipeline steps does not include a property such as termination_signal or grace_period_seconds. Treat the exit-code mapping as a strong convention, not a guaranteed API contract, because runner internals can change without notice.

Steps that work within these constraints

1. Trap SIGTERM inside your own process. Because Bitbucket will not call a pre-stop script, your application or wrapper script must install its own signal handler. For example, a shell wrapper can trap 'cleanup' TERM before exec'ing the main process.
2. Keep cleanup under 10 seconds. The fixed interval leaves no room for slow flushes. If your shutdown path closes database connections or flushes logs, measure it and ensure it completes well before the SIGKILL deadline.
3. Prefer explicit timeouts over manual cancellation. Set a timeout in the step definition so the runner initiates the same signal sequence deterministically, rather than relying on a human clicking cancel at an arbitrary moment.
4. Verify exit codes in logs. After a timeout or cancellation, inspect the step log for the exit status. A 143 indicates the process received SIGTERM; 137 indicates it was killed by SIGKILL after the grace period expired.

One diagnostic detail that changes the recommendation

If your graceful shutdown routinely needs more than 10 seconds, in-process signal trapping will not be sufficient, and the correct pattern is to move cleanup out of the step entirely—for example, by writing a completion marker to durable storage and letting a separate worker finish the job. If cleanup is under 10 seconds, the steps above are enough. How long does your shutdown path typically take?

Version assumption: This reflects Bitbucket Cloud Pipelines behavior as documented through 2024. Self-hosted runner environments may offer different low-level controls; verify against your specific runner version before relying on undocumented internals.