Approval rule API documentation is confusing
Problem to solve
The API documentation for project approval rules confused me. An approval rule, as returned from the API, includes a rule_type
field that appears to have two possible values: any_approver
or regular
. However, the API call to create an approval rule is not documented as accepting a rule_type
field. Based on this, I assumed that the any_approver
rule always existed and could not be deleted or created, and indeed the project I was testing on had one with approvals_required
set to 0. However, it turns out that my assumption was incorrect; a newly created project, even though the UI shows an approval rule with approvals_required
set to 0, has no approval rules, and it is necessary to create one if the desire is to set approvals_required
to a non-zero value. If that rule is created with a name of "All Members" and a non-zero approvals_required
, and no other options, the rule automatically becomes an any_approver
rule, but there is no documentation about what the exact required criteria are: is the name
important? Must the list of approvers be omitted? Further, the API documentation doesn't list the possible values for rule_type
or what they mean.
Further details
Links:
- https://gitlab.com/help/api/merge_request_approvals.md#get-project-level-rules
- https://gitlab.com/help/api/merge_request_approvals.md#create-project-level-rule
Proposal
The documentation should be clarified around these points:
- What are the types of rules and how do they function?
- How can each rule type be created?
- Are there rule types that cannot be deleted?
- How is the "default" rule represented? That is, why is it not present on a newly-created project, but remains present if it is created, then set back to
approvals_required = 0
? - Are there future directions for this API and the corresponding UI that are expected to change how this functions?
(It would also be useful if there were a write-up correlating API settings and the corresponding presentation in the UI.)
Who can address the issue
Someone familiar with how the approval rules API is actually implemented; I have too many questions to be able to contribute the required changes!