About Automerge Action

This action is intended to be used in tandem with a CI workflow. This workflow requires a github token with read/write access to all the repositories it will be tracking

Any PRs that meet the following criteria will be automerged:

• PR is open
• PR is mergeable
• PR is passing test
• PR is approved by at least one reviewer
• PR is up-to-date with the base branch

Any PR with the following criteria will be updated and test will be run before merging:

• PR is open
• PR is approved
• PR is passing PR Tests
• PR is out-of-date

A Github App is required to generate the appropriate Permissions for Automerge to work.

• The Github App is not public and requires each org to generate their own.
  Adding a token generation step to their automerge workflow. See Example Workflow below.
• Specific repositories can be granted access using the app instead of ALL repositories under the org.

Github App Permissions:

• Content Read/Write -- For Updating PRs
• Pull Request Read/Write -- For Updating PRs
• Repository Administration Read -- For read access to repositories under the Org.
• Checks Read -- For reading the check statuses of the PR

Table of Contents

• Automerge PR Action
  • Table of Contents
  • Inputs
  • Outputs
  • Example workflow using Automerge across a Github Organization
  • The Workflow
  • Reduce CI Pressure
  • Run Locally

Example workflow using Automerge across a Github Organization

This example workflow will run every 20 minutes and will automerge PRs for tracked repositories in the organization.

This workflow is recommended for setup in a CI/CD Devops dedicated repostiory.

For the example a JSON file called automerge.json contains a list of repositories to track PR status for merging/updates. The JSON file should be in the following format:

[
  "repo1",
  "repo2",
  "repo3"
]

The Workflow

In a workflow we will call .github/workflows/automerge.yml. The workflow will run as many jobs in parallel as possible.

name: Example Automerge Workflow
on:
  workflow_dispatch:
  schedule:
    - cron: '*/20 * * * *'
jobs:
  list:
    name: 'List Repos'
    runs-on: [ubuntu-latest]
    outputs:
      matrix: ${{ steps.list.outputs.value }}
    steps:
      - name: 'Check out devops repo'
        uses: actions/[email protected]
      - id: list
        name: 'List automerge repos'
        run: echo "value=$(cat test/automerge.json | tr -d '\n')" >> $GITHUB_OUTPUT
      - name: 'Generate GitHub App Token'
        id: automerge_token
        uses: actions/[email protected]
        with:
          app_id: ${{ secrets.AUTOMERGE_APP_ID }}
          private_key: ${{ secrets.AUTOMERGE_APP_PRIVATE_KEY }}

  automerge-test:
    name: 'Automerge'
    runs-on: [ubuntu-latest]
    needs: list
    strategy:
      fail-fast: false
      matrix:
        value: ${{fromJson(needs.list.outputs.matrix)}}
    steps:
      - name: 'Automerge runtimeverification/${{ matrix.value }}'
        uses: runtimeverification/[email protected] # This uses the action in the root directory
        with:
          org: 'runtimeverification' # As long as the token you use has access, any org is valid here
          repo: ${{ matrix.value }}
          token: ${{ secrets.GITHUB_PAT }}

Reduce CI Pressure

If less CI Pressure is desired, the workflow can be modified to run on sequentially

name: Test Workflow
on:
  workflow_dispatch:
  schedule:
    - cron: '*/20 * * * *'
...
...
...
  automerge-test:
    name: 'Automerge'
    runs-on: [ubuntu-latest]
    needs: list
    strategy:
      fail-fast: false
      max-parallel: 1 # Or any integer up to 256 set by github actions run limit. 
      matrix:
        value: ${{fromJson(needs.list.outputs.matrix)}}
    steps:
...
...

Run Locally

Checkout the repository you wish to run automerge on to a local directory.

git clone [email protected]:org/automerge.git
cd automerge

Setup GITHUB_TOKEN with the appropriate permissions: Content Read/Write, Pull Request Read/Write, Adminstration Read, Checks Read. Now you need to run the command from this new directory. RV setup a test repository with Pull Requests in Known States to validate the action is working as expected.

$(pwd)/../src/automerge.py --org runtimeverification --repo automerger-test --dry-run

Recommended to first review the actions before running without. Then remove the --dry-run flag to run the action.

Testing

test.yaml

Purpose:

• The purpose of the test is to import automerger action.
• Evaluate the test Scenarios of a Live Test Setup and Report back the values

Usage:

• The test.yaml file is used by the automerger to determine which pull requests to merge and under what conditions.
• It specifies the target repository, the specific states of the pull requests to test against, and the actions to perform.

Note:

• Results MUST BE MANUALLY VERIFIED BEFORE MERGE
• The test.yaml file should be updated whenever there are changes to the test scenarios or configurations.
• It is important to ensure that the test.yaml file accurately reflects the desired behavior of the automerger.

For more information, please refer to the following resources:

• Link to the repository rutimeverification/automerger-test
• Link to the live pull requests in the repository