What's the fastest way to check if branch is up to date with the main branch?

[gajus]

This is what we are using at the moment:

  before_all:
    name: 'before all'
    runs-on:
      - self-hosted
      - contra-general-purpose
    steps:
      - name: git checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: check if branch is ahead of main
        run: |
          if ! git merge-base --is-ancestor origin/main ${{ github.event.pull_request.head.sha }};
          then echo "This branch is not up to date with main";
          exit 1; fi
      - run: echo "Starting CI"

However, this step is taking upwards of 2 minutes in our large repository.

[ericsondea-collab]

csl c,f , v v v~xclvv xvd çdm, d ~dg sç, fdç

[SebTardif]

@gajus

this step is taking upwards of 2 minutes in our large repository

fetch-depth: 0 is what costs you the two minutes. You do not need a full clone to answer "is this PR head behind main?"

Skip checkout for this gate and use the Compare API. behind_by is the number of commits on the base that are not in the head:

- name: Require PR head contains latest base
  env:
    GH_TOKEN: ${{ github.token }}
  run: |
    base='${{ github.event.pull_request.base.ref }}'
    head='${{ github.event.pull_request.head.sha }}'
    behind=$(gh api "repos/${GITHUB_REPOSITORY}/compare/${base}...${head}" --jq '.behind_by')
    echo "behind_by=${behind}"
    if [ "${behind}" != "0" ]; then
      echo "This branch is ${behind} commit(s) behind ${base}"
      exit 1
    fi

That matches what your merge-base --is-ancestor origin/main <head.sha> check is asking, without downloading history.

Notes:

• Use pull_request.head.sha, not github.sha. On pull_request events github.sha is the temporary merge commit, which is already based on current main.
• Default GITHUB_TOKEN can call this endpoint.
• If the real goal is "do not merge until CI is current," turn on the branch rule "Require branches to be up to date before merging" and drop this job.

If you still want a git-only check, fetch only main at depth 1. Do not use fetch-depth: 0. Shallow merge-base --is-ancestor is unreliable when the two tips do not share objects in the shallow window, so the Compare API is the better fit for a large repo.