Merging pull requests using GitHub Actions

Automating the process to merge pull requests in GitHub Actions accelerates development workflows, reduces manual intervention, and ensures consistent integration practices. This guide explores methods to automate pull request merges using GitHub Actions, with a focus on the automerge-action and Graphite Automations.

Enabling auto-merge in GitHub

GitHub provides a native auto-merge feature that automatically merges pull requests when all required checks and reviews are completed. To enable this:

1. Navigate to your repository on GitHub.
2. Click on "Settings."
3. Under the "General" tab, scroll to "Pull Requests."
4. Check the box for "Allow auto-merge."

Once enabled, contributors can opt-in to auto-merge for individual pull requests. The pull request will merge automatically once it meets all the required conditions, such as passing status checks and receiving necessary approvals.

Using the automerge-action

For more granular control over the merge process, the automerge-action GitHub Action can be utilized. This action allows for automated merging based on specific labels, merge methods, and other criteria.

Setup:

Create a workflow file .github/workflows/automerge.yml with the following content:

name: automerge
on:
  pull_request:
    types:
      - labeled
      - unlabeled
      - synchronize
      - opened
      - edited
      - ready_for_review
      - reopened
      - unlocked
  pull_request_review:
    types:
      - submitted
  check_suite:
    types:
      - completed
  status: {}
jobs:
  automerge:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - id: automerge
        name: automerge
        uses: pascalgn/automerge-action@v0.16.4
        env:
          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
          MERGE_LABELS: "automerge,!wip,!work in progress"
          MERGE_METHOD: "squash"
          MERGE_REQUIRED_APPROVALS: "1"

Key configuration options:

• MERGE_LABELS: Specifies labels required for a pull request to be eligible for auto-merge. Prefixing a label with ! indicates that the presence of that label will block the merge.
• MERGE_METHOD: Determines the merge strategy (merge, squash, or rebase).
• MERGE_REQUIRED_APPROVALS: Sets the number of required approvals before merging.

This setup ensures that only pull requests labeled with automerge and without any blocking labels like wip or work in progress are automatically merged using the squash method after receiving at least one approval.

Integrating Graphite Automations

Graphite Automations offers advanced capabilities for managing pull request merges, especially in complex repositories or monorepos. It allows for the creation of custom merge rules based on various criteria, such as file paths, team ownership, or specific CI checks. By defining specific rules, teams can streamline their pull request processes, ensuring that code reviews and merges adhere to organizational standards. This automation reduces manual intervention, accelerates development cycles, and maintains consistency across repositories.

Best practices for automating pull request merges

• Use descriptive labels: Clearly label pull requests intended for auto-merge to avoid unintended merges.
• Implement branch protection rules: Ensure that critical branches have protection rules requiring status checks and approvals.
• Monitor merge activities: Regularly review merged pull requests to ensure that the automation behaves as expected.
• Combine tools effectively: Utilize GitHub's native auto-merge, automerge-action, and Graphite Automations in tandem to achieve a balance between automation and control.

By adopting these practices, teams can maintain a robust and efficient workflow for managing pull request merges in GitHub.