We're trying to use the GitLab API to automate the merge request lifecycle based on the movement of Jira tickets.
Using the /merge_requests endpoint, I can see the merge_status field which seems to contain one of the following values: unchecked, can_be_merged, cannot_be_merged, cannot_be_merged_recheck, or checking.
Question 1: is there any documentation on what the individual status values mean, and what can trigger these being returned?
I can also see the use of the with_merge_status_recheck [option]https://docs.gitlab.com/ee/api/merge_requests.html) (added in 13.0) which controls how the merge_status field is updated/reported.
The API documentation states:
- Introduced in GitLab 12.8, the mergeability (
merge_status) of each merge request is checked asynchronously when a request is made to this endpoint. Poll this API endpoint to get updated status. This affects thehas_conflictsproperty as it is dependent on themerge_status. It returnsfalseunlessmerge_statusiscannot_be_merged.- Introduced in GitLab 13.0, listing merge requests may not proactively update
merge_status(which also affects thehas_conflicts), as this can be an expensive operation. If you need the value of these fields from this endpoint, set thewith_merge_status_recheckparameter totruein the query.
And the parameter option says:
with_merge_status_recheck-- Iftrue, this projection requests (but does not guarantee) that themerge_statusfield be recalculated asynchronously. Default isfalse.
Question 2: If I call GET https://gitlab.com/api/v4/projects/:project_id/merge_requests/:id?with_merge_status_recheck=true, what is the expected outcome? The parameter documentation indicates that with_merge_status_recheck initiates an asynchronous calculation, but how do I know when the value of merge_status is accurate, and I can rely on it?
I've tried timing a call with with_merge_status_recheck=true, and =false, and there are no obvious performance deviations that can indicate what's happening.
