In GitHub, in the branch protection settings, you can require branches to be up to date before merging (this is possible both for both GitHub Enterprise and for public repos in free GitHub):
Then on a PR, if the branch is not up to date with the base branch, and this base branch is protected in this way, you will see the following in the UI:
Using the GitHub API, is there any way to detect if a branch is out of date relative to a base branch, or to detect if a PR is such that the head branch is out-of-date with the base branch?
I am working with a GitHub Enterprise instance, so unique features of the GitHub Enterprise API can be included in any answers.
I already looked through the GitHub Enterprise API docs in some detail, and I didn't see a way to detect this, but it is very possible I missed something.
Unless I am mistaken, this can be done by using the compare commits API endpoint.
You can make a request to this API endpoint, and then check the behind_by
part of the JSON response. If this value is 0, the head branch is up-to-date relative to the base branch; else, the head branch is not up-to-date relative to the base branch.