Add an API that allows users to hard reset a branch.
Problem to solve
Develop an API that allows users to hard reset (or update) a branch to a given SHA. Currently, we achieve this by a DELETE request and a POST request to recreate the branch. Doing this is error prone, because we could end up in a situation where the DELETE succeeds and the POST fails.
Intended users
- Developers
- Automated Release Systems
Further details
Benefits:
- This can be one atomic operation rather than introducing the failure modes of doing a DELETE and then a POST.
Use Cases:
- Our automated deploy system resets a branch to what is currently deployed in production.
Proposal
By adding an endpoint in the Branches API.
Permissions and Security
It should be consistent with the existing API permissions for the Branches API.
Documentation
New documentation would need to be added to the Branches API page.
Testing
A user might accidentally reset a branch where someone has pushed changes underneath them, which would overwrite their changes. There are a few mitigations for this. The API could include a force flag and a way to specify their the SHA they expect to overwrite.
What does success look like, and how can we measure that?
My assumption is that you gather metrics on API usage. Success would mean others find this useful and use it as part of their workflow.