redhat-plumbers-in-action / auto-merge

💫 GitHub Action that merges PR if specified conditions are met

Auto Merge

Auto Merge is a GitHub Action that automaticaly merges Pull Requests. It works best togetger with Advanced Commit Linter, Tracker Validator and Pull Request Validator GitHub Actions. But it can be used separately.

Features

• Ability to merge Pull Request automatically
• Ability to block merge of Pull Request based on Pull Request title and labels
• Ability to set ready to merge label on Pull Request

Usage

name: Gather Pull Request Metadata
on:
  pull_request:
    types: [ opened, reopened, synchronize ]
    branches: [ main ]

permissions:
  contents: read

jobs:
  gather-metadata:
    runs-on: ubuntu-latest

    steps:
      - name: Repository checkout
        uses: actions/checkout@v3

      - id: Metadata
        name: Gather Pull Request Metadata
        uses: redhat-plumbers-in-action/gather-pull-request-metadata@v1

      - name: Upload artifact with gathered metadata
        uses: actions/upload-artifact@v3
        with:
          name: pr-metadata
          path: ${{ steps.Metadata.outputs.metadata-file }}

name: Pull Request Validator
on:
  workflow_run:
    workflows: [ Gather Pull Request Metadata ]
    types:
      - completed

permissions:
  contents: read

jobs:
  download-metadata:
    if: >
      github.event.workflow_run.event == 'pull_request' &&
      github.event.workflow_run.conclusion == 'success'
    runs-on: ubuntu-latest

    outputs:
      pr-metadata: ${{ steps.Artifact.outputs.pr-metadata-json }}

    steps:
      - id: Artifact
        name: Download Artifact
        uses: redhat-plumbers-in-action/download-artifact@v1
        with:
          name: pr-metadata

  auto-merge:
    needs: [ download-metadata ]
    runs-on: ubuntu-latest

    permissions:
      # required for ability to merge Pull Request
      contents: write
      # required for status checks
      checks: write
      # required for setting labels
      pull-requests: write

    steps:
      - id: commit-linter
        name: Commit Linter
        uses: redhat-plumbers-in-action/advanced-commit-linter@v2
        with:
          pr-metadata: ${{ needs.download-metadata.outputs.pr-metadata }}
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Auto Merge
        uses: redhat-plumbers-in-action/auto-merge@v1
        with:
          pr-metadata: ${{ needs.download-metadata.outputs.pr-metadata }}
          tracker: ${{ fromJSON(steps.commit-linter.outputs.validated-pr-metadata).validation.tracker.id }}
          tracker-type: ${{ fromJSON(steps.commit-linter.outputs.validated-pr-metadata).validation.tracker.type }}
          bugzilla-instance: https://bugzilla.redhat.com
          bugzilla-api-token: ${{ secrets.BUGZILLA_API_TOKEN }}
          jira-instance: https://issues.redhat.com
          jira-api-token: ${{ secrets.JIRA_API_TOKEN }}
          token: ${{ secrets.GITHUB_TOKEN }}

Configuration options

Action currently accepts the following options:

# ...

- uses: redhat-plumbers-in-action/auto-merge@v1
  with:
    pr-metadata:        <pr-metadata.json>
    config-path:        <path to config file>
    tracker:            <tracker ID>
    tracker-type:       <tracker type>
    bugzilla-instance:  <Bugzilla instance URL>
    bugzilla-api-token: <Bugzilla API token>
    jira-instance:      <Jira instance URL>
    jira-api-token:    <Jira API token>
    set-status:         <true or false>
    status-title:       <status title>
    token:              <GitHub token or PAT>

# ...

pr-metadata

Stringified JSON Pull Request metadata provided by GitHub Action redhat-plumbers-in-action/gather-pull-request-metadata.

Pull Request metadata has the following format: metadata format

• default value: undefined
• requirements: required

config-path

Path to configuration file. Configuration file format is described in: Configuration section.

• default value: .github/tracker-validator.yml
• requirements: optional

tracker

The tracker identificator. For example, for Bugzilla: tracker: 1234567.

• default value: undefined
• requirements: required

tracker-type

The tracker type. Currently supported: bugzilla and jira.

• default value: undefined
• requirements: required

bugzilla-instance

The URL of the Bugzilla instance on which will be performed API requests and validation of trackers. For example: bugzilla-instance: https://bugzilla.redhat.com.

• default value: undefined
• requirements: optional

bugzilla-api-token

The Bugzilla API token is used for performing API requests. The token should be stored as GitHub secret. Never paste the token directly into the workflow file.

• default value: undefined
• requirements: optional

jira-instance

The URL of the Jira instance on which will be performed API requests and validation of trackers. For example: jira-instance: https://issues.redhat.com.

• default value: undefined
• requirements: required

jira-api-token

The Jira API token is used for performing API requests. The token should be stored as GitHub secret. Never paste the token directly into the workflow file.

• default value: undefined
• requirements: optional

set-status

Set status on Pull Request. If enabled, Action will create check-run status with validation results.

• default value: false
• requirements: optional

status-title

Optional H3 title of status message.

• default value: Auto Merge
• requirements: optional

token

GitHub token or PAT is used for creating comments on Pull Request and setting checks.

# required permission
permissions:
  contents: write
  checks: write
  pull-requests: write

• default value: undefined
• requirements: required
• recomended value: secrets.GITHUB_TOKEN

Outputs

status

Message with status of Auto Merge action.

Configuration

Action can be additionally configured by creating a configuration file in the repository. The configuration file should be placed in .github/auto-merge.yml (it can be changed by setting config-path option). The configuration file has the following format:

labels:
  dont-merge: dont-merge
  manual-merge: pr/needs-manual-merge
title-prefix': ['WIP:', '[WIP]:']
target-branch': ['main', 'master']

labels keyword

Allows you to set custom labels for certain conditions.

dont-merge keyword

The name of the label that will block the merge of the Pull Request.

• default value: dont-merge

manual-merge keyword

The name of the label that will be set on the Pull Request if the merge have to be performed manually.

• default value: pr/needs-manual-merge

title-prefix keyword

The list of Pull Request title prefixes that will block the merge of the Pull Request. Usually used for marking Pull Request as Work In Progress.

• default value: ['WIP:', '[WIP]:']

target-branch keyword

The target branches on which the Pull Request will be automatically merged. If the Pull Request is not targeting any of the listed branches and all requirements are satisfied, the Pull Request will be marked by a manual-merge label.

• default value: ['main', 'master']

Limitations

• Status checks from Pull Request Validator are randomly assigned to check suites, GitHub API for check suites doesn't provide a way to assign a check to a specific suite.
• Specific branch protection rules might block the merge of a Pull Request even if all requirements are satisfied. If you encounter a message like this: Error: You're not authorized to push to this branch. Visit https://docs.github.com/articles/about-protected-branches/ for more information. you should check your branch protection rules. The issue is usually caused by the Restrict who can push to matching branches option.