Merge request API + merge_status

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]Merge requests API | GitLab) (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 the has_conflicts property as it is dependent on the merge_status . It returns false unless merge_status is cannot_be_merged .
• Introduced in GitLab 13.0, listing merge requests may not proactively update merge_status (which also affects the has_conflicts ), as this can be an expensive operation. If you need the value of these fields from this endpoint, set the with_merge_status_recheck parameter to true in the query.

And the parameter option says:

with_merge_status_recheck – If true , this projection requests (but does not guarantee) that the merge_status field be recalculated asynchronously. Default is false .

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.

I’d be very interested in an answer to this question. In marge-bot, when the bot is trying to merge an MR, if the merge_status is false, we run a linear-backoff. If merge_status does not resolve to true after three attempts, we assume that false is the correct value.

If there’s a way to do this via the API, then even better.