"Forbid merge commits" GitHub Action

This action enforces clean semi-linear git history that looks like this:

It fails on Pull Requests that include merge commits.

This rule is designed to prevent developers from merging the base branch into their branch as a way of making it up-to-date. This creates foxtrot commits and confusing git log graphs.

This rule is also designed to prevent using GitHub's "Update Branch" button, which merges the base branch into the source branch. Instead, use the pull-down "Rebase Branch" button. This rebases the source branch onto the base branch. This is a common problem if "Always suggest updating pull request branches" is enabled, because "Update Branch" is the default choice in the pull-down and it cannot be disabled or changed.

Failure messages

When this action fails, it leaves instructions pointing here to this README.md on how to handle the failures.

Example failure message in check logs:

Example failure message in checks summary:

Handling failure messages

If this action fails due to the presence of merge commits, it will print out the offending commits and fail the workflow. To resolve this, you will need to rebase your branch onto the base branch.

If the "Rebase Branch" button is available, you can use that.

Otherwise, you can rebase your branch locally using the following commands:

git pull <upstream-remote> <base-branch> --rebase
git push --force-with-lease origin <branch_name>

The <upstream-remote> is usually named upstream or origin. The <base-branch> is usually named main or master.

When this action may not be applicable

Sometimes including merge commits in Pull Requests is acceptable. For example, when maintaining a library it is common to fix problems on stable branches and merge the fixes into the default branch. In such cases, you may want to configure this action to run only on some branches, or remove it entirely.

How to add this action to your repository

This action is designed to trigger only on: pull_request events. To add this action to your repository, you can add it to an existing workflow file that triggers only on Pull Requests, or create a new workflow file.

To add this action to your repository, you need to create a new workflow file in the .github/workflows/ directory.

Here is an example .github/workflows/pull-request.yml workflow.

on: pull_request

jobs:
  forbid-merge-commits:
    runs-on: ubuntu-latest
    steps:
      - name: Run Forbid Merge Commits Action
        uses: motlin/forbid-merge-commits-action@main

Recommended settings

This action is designed to be used with the settings "Allow merge commits" and "Always suggest updating pull request branches."

How is this different from the "Require Linear History" status check?

"Require linear history" does not allow merges at all. It is used with "Squash and Merge" or "Rebase and Merge" and creates a completely linear history.

This workflow is meant to be used with the "Merge" button on Pull Requests. These merge commits let us see who clicked the merge button, and which commits were grouped together into a single Pull Request with multiple commits.

Prior art

This action is similar to cyberark/enforce-rebase, which runs using a deprecated version of Node. This action is implemented as a Composite Action using yaml, which is easier to keep up-to-date.