search

pascalgn / automerge-action

GitHub action to automatically merge pull requests that are ready
MIT License
859 stars 210 forks source link
github github-action github-api

readme

automerge-action

GitHub action to automatically merge pull requests when they are ready.

When added, this action will run the following tasks on pull requests with the automerge label:

Labels, merge and update strategies are configurable, see Configuration.

A pull request is considered ready when:

  1. the required number of review approvals has been given (if enabled in the branch protection rules) and
  2. the required checks have passed (if enabled in the branch protection rules) and
  3. the pull request is up to date (if enabled in the branch protection rules)

After the pull request has been merged successfully, the branch will not be deleted. To delete branches after they are merged, see automatic deletion of branches.

This functionality is now available directly in GitHub as auto-merge. Note that GitHub does not currently support auto-rebasing pull requests. The automerge-action project will still be maintained, but users are encouraged to switch to auto-merge for simple workflows, as it offers a faster and more stable experience.

Usage

Create a new .github/workflows/automerge.yml file:

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 }}"

For the latest version, see the list of releases.

Configuration

The following merge options are supported:

The following update options are supported:

Also, the following general options are supported:

You can configure the environment variables in the workflow file like this:

        env:
          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
          MERGE_LABELS: "automerge,!work in progress"
          MERGE_REMOVE_LABELS: "automerge"
          MERGE_METHOD: "squash"
          MERGE_COMMIT_MESSAGE: "pull-request-description"
          MERGE_FORKS: "false"
          MERGE_RETRIES: "6"
          MERGE_RETRY_SLEEP: "10000"
          MERGE_REQUIRED_APPROVALS: "0"
          UPDATE_LABELS: ""
          UPDATE_METHOD: "rebase"
          PULL_REQUEST: "1234"
          MAX_PR_COUNT: "25"

Supported Events

Automerge can be configured to run for these events:

For more information on when these occur, see the Github documentation on events that trigger workflows and their payloads.

Outputs

The action will provide two outputs:

Please note:

  1. When there are multiple pull requests affected, only the first one will be available in the output
  2. To access these outputs, your workflow configuration must define an id for the automerge-action step
  3. Unless a personal access token is used, this action will not trigger other actions, see Limitations

Example usage:

    steps:
      - id: automerge
        name: automerge
        uses: "pascalgn/automerge-action@v0.15.6"
        env:
          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
      - name: feedback
        if: ${{ steps.automerge.outputs.mergeResult == 'merged' }}
        run: |
          echo "Pull request ${{ steps.automerge.outputs.pullRequestNumber }} merged!"

Limitations

Debugging

To run the action with full debug logging, update your workflow file as follows:

      - name: automerge
        uses: pascalgn/automerge-action@...
        env:
          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
          LOG: "TRACE"  # or "DEBUG"

If you need to further debug the action, you can run it locally.

You will need a personal access token.

Then clone this repository, create a file .env in the repository, such as:

GITHUB_TOKEN="123abc..."
URL="https://github.com/pascalgn/repository-name/pull/123"

Install dependencies with yarn, and finally run yarn it (or npm run it).

License

MIT