League Fork of Merge Gatekeeper

The original project seems to be unmaintained and there are a few bugs that would be good to resolve, hence this internal fork.

Merge Gatekeeper

Merge Gatekeeper provides extra control for Pull Request management.

🌄 What Does Merge Gatekeeper Provide, and Why?

Pull Request plays a significant part in day-to-day development, and it is essential to ensure all merges are well controlled and managed to build robust system. GitHub provides controls over CI, reviews, etc., but there are some limitations around handling specific use cases. Merge Gatekeeper helps overcome those by adding extra controls, such as monorepo friendly branch protection.

At UPSIDER, we have a few internal repositories set up with a monorepo structure, with many types of code in a single repository. This comes with its own pros and cons, but one difficulty is how we end up with various CI jobs, which only run for changes that touch relevant files. With GitHub's branch protection, there is no way to specify "Ensure Go build and test pass if and only if Go code is updated", or "Ensure E2E tests are run and successful if and only if frontend code is updated". This is due to the GitHub branch protection design to specify a list of jobs to pass, which is only driven by the target branch name, regardless of change details. Because of this limitation, we would either need to run all the CI jobs for any Pull Requests, or do not set any limitation based on the CI status. _^(*1)

Merge Gatekeeper was created to provide more control for merges. By placing Merge Gatekeeper to run for all PRs, it can check all other CI jobs that get kicked off, and ensure all the jobs are completed successfully. If there is any job that has failed, Merge Gatekeeper will fail as well. This allows merge protection based on Merge Gatekeeper, which can effectively ensure any CI failure will block merge. All you need is the Merge Gatekeeper as one of the PR based GitHub Action, and set the branch protection rule as shown below.

We are looking to add a few more features, such as extra signoff from non-coder, label based check, etc.

_{^{NOTE:
(*1) There are some other hacks, such as using an empty job with the same name to override the status, but those solutions do not provide the flexible control we are after.}}

You can find more details here.

🚀 How Can I Use Merge Gatekeeper?

The easiest approach is to copy the standard definition, and save it under .github/workflows directory. There is no further modification required unless you have some specific requirements.

With curl

curl -sSL https://raw.githubusercontent.com/EverlongProject/merge-gatekeeper/main/example/merge-gatekeeper.yml \
  > .github/workflows/merge-gatekeeper.yml

Directly copy YAML

The below is the copy of /example/merge-gatekeeper.yml, with extra comments.

---
name: Merge Gatekeeper

on:
  pull_request:
    branches:
      - main
      - master

jobs:
  merge-gatekeeper:
    runs-on: ubuntu-latest
    # Restrict permissions of the GITHUB_TOKEN.
    # Docs: https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs
    permissions:
      actions: read
      checks: read
      statuses: read
    steps:
      - name: Run Merge Gatekeeper
        # NOTE: v1 is updated to reflect the latest v1.x.y. Please use any tag/branch that suits your needs:
        #       https://github.com/EverlongProject/merge-gatekeeper/tags
        #       https://github.com/EverlongProject/merge-gatekeeper/branches
        uses: EverlongProject/merge-gatekeeper@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

You can find more details here.

If your CI generates jobs dynamically and GitHub can register those child jobs slightly after Merge Gatekeeper first sees the workflow as green, set success-confirmation-polls to require additional consecutive successful polls before the action exits. Leave it at the default 0 unless you need that extra confirmation window.

🧪 Action Inputs

There are some customisation available for Merge Gatekeeper.

Name	Description	Required
token	GITHUB_TOKEN or Personal Access Token with repo scope	Yes
self	The name of Merge Gatekeeper job, and defaults to merge-gatekeeper. This is used to check other job status, and do not check Merge Gatekeeper itself. If you updated the GitHub Action job name from merge-gatekeeper to something else, you would need to specify the new name with this value.
interval	Check interval to recheck the job status. Default is set to 5 (sec).
timeout	Timeout setup to give up further check. Default is set to 600 (sec).
success-confirmation-polls	Number of additional consecutive successful polls required after Merge Gatekeeper first sees all validations as green. 0 keeps the current behavior.
ignored	Jobs to ignore regardless of their statuses. Defined as a comma-separated list and matched by exact check name. Use the full check names shown in GitHub, for example CodeQL / Analyze (go),CodeQL / Analyze (javascript).
ignore-dynamic-github-workflows	Ignore check runs whose backing workflow run resolves to a GitHub-managed workflow path under dynamic/. This is useful for GitHub-generated workflows such as Copilot review jobs that are not declared in the repository itself. Defaults to true; set it to false to keep those checks in scope.
ref	Git ref to check out. This falls back to the HEAD for given PR, but can be set to any ref.

If you want to exclude CodeQL or other GitHub Advanced Security checks from merge gating, use ignored with the exact check names shown in GitHub. Those checks do not always have a backing workflow run in the Actions workflow-runs API, so ignore-dynamic-github-workflows does not exclude them.

You can find more details here.