Skip to content

Github Pull Request Management Runtime Verification

Notifications You must be signed in to change notification settings

runtimeverification/automerge

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

30 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

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/checkout@v4.0.0
      - 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/create-github-app-token@v1.11.0
        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/automerge@v1.0.4 # 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 git@github.com: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

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:

About

Github Pull Request Management Runtime Verification

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages