Add additional capabilities to the Commits Revert API

Problem to solve

Customization desires for Reverts

Intended users

• Sasha (Software Developer)
• Devon (DevOps Engineer)
• Sidney (Systems Administrator)

Further details

It would be neat if I could customize the commit message of a Revert that is executed on the API. For systems that may use the Revert API, this customization can add context, or commands that prevent CI jobs from running. Example:

graph TD
A[deploy] -->B[Success?]
B -->|Yes| C[do something]
B -->|No| D[Rollback]
D --> E[Revert]

Let's say we execute a deploy. If that deploy is successful, just finish up your CI/CD tasks. If the deploy has failed, a common occurrence may be to roll back the deployment for safety. This creates a situation where what is on the mainline branch (examples, master or production) contains a state that does not match that of what is running on the system. Using the Revert API would be helpful in producing a commit that indicates the current state. The capability to perform a Revert via the API exists today, but we lack some critical capabilities. Primarily the desire to customize the commit message on the Revert. GitLab currently chooses a default message:

Revert "foo"
> This reverts commit f2070e52

However, it'd be nice to add some context. Example:

Revert "foo"
> This reverts commit f2070e52 due to a failed deploy

And since we have GitLab CI doing some of the work for us, we can add Pipeline information:

Revert "foo"
> This reverts commit f2070e52 due to a failed deploy
> See pipeline !51

And since we have a use case where the deployment system performed a rollback, it'd be nice if this new revert doesn't create a new pipeline, so another example might be:

Revert "foo"
> This reverts commit f2070e52 due to a failed deploy
> [skip ci]

Proposal

curl \
  --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "branch=master" \
  --form "commit_message='Revert "foo"\n> This reverts commit f2070e52 due to a failed deploy\n> [skip ci]' \
  "https://gitlab.example.com/api/v4/projects/5/repository/commits/f2070e52/revert"

Or something similar.

Permissions and Security

There should be no need to adjust permission as this appears to be a handler built into the existing Commits API that should already contain the necessary permission models.

Testing

If setup incorrectly, one may end up in a Revert Loop as one Engineer found out: https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/7580#note_215024995

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

Success can be seen when we can customize the commit message in a revert commit.