Introduce graceful-cancellation state for CI Pipelines

Problem to solve

Currently, cancelling a pipeline immediately stops execution of all running jobs. We have an issue open to implement a graceful cancellation of individual jobs #35356 (closed), and this should be extended to Ci::Pipeline, where graceful cancellation sends the newly-implemented graceful cancellation to all of its builds. created and pending builds would be cancelled immediately, while running builds move immediately move on into their after_script.

Intended users

This problem might apply to anyone cancelling a pipeline: manually via the web UI, through the API, or implicitly by kicking off a pipeline while a running pipeline on the same ref has interruptible: true jobs.

Further details

This is the second step after introducing graceful cancellation for running jobs. These two issues, along with a change in the runner (link here when available) will completely address #15603 (closed).

Proposal

Implement #graceful_cancel (but with a better name?) on Ci::Pipeline to gracefully cancel all jobs in the pipeline.

Permissions and Security

Access would be available on the same basis as Pipeline cancellation is today, no changes required.

Documentation

Testing

1. Unit testing for the state change and messages sent to the pipeline jobs.

What does success look like, and how can we measure that?

Folks can automatically tear down docker resources when they cancel an entire pipeline.

What is the type of buyer?

Links / references