Documentation about "mergeable_state"


#1

On GET https://api.github.com/repos/:owner/:repo/pulls/:number API

“mergeable_state” attribute seems to have many state: dirty, clean, blocked, behind…

But the documentation does not expose the complete list or explain them.

Can we have more detail on this ?


#2

Thanks for bringing this to our attention, @sileht. I’ve created an internal issue to track getting this information properly added to the docs. In the meantime, if you have questions about a particular state or states, I’d be happy to get you some information in this thread.


#3

I’d like some info on this. We auto merge on green and try to detect the green merge using mergeable_state. ‘unstable’ is the only one i’ve seen that has confused me. Rest seem self explanatory.


#4

@jmilas Hi, are you still working on this issue?
I need all state information. Can you provide it for us?

My guess is:

  • clean means It can be merged without any concerns. Literally It is CLEAN.
  • behind means the branch is out-of-date.
  • dirty means there are conflicts with base branch.
  • unstable means The CI is running or failed, not success. So we need to check the state to check if it can be merged safely.

Is it right? and are there other states?


#5

Can anyone explain it? :frowning:


#6

The best docs for this are in the GraphQL docs:

https://developer.github.com/v4/enum/mergestatestatus/

:v:


#7

@greysteil Could you explain the blocked state in more detail please? I can’t understand when it happens.

I think that if CI is running, the mergeable_state will be unstable, but sometimes it is blocked. I’m so confused.


#8

Sure thing. You’ll see blocked if there are required status checks that haven’t yet passed.

(Disclaimer: I don’t work for GitHub, just lots of experience working with the API on Dependabot.)


#9

But sometimes mergeable_state also returns unstable when CI is running. That’s why I am confused now.

Am I misunderstanding?


#10

You can set required status checks as a branch security measure. If those are set you’ll get blocked, otherwise you’ll get unstable.


#11

I cannot thank you enough! :slight_smile:


#12

See also: