acaloiaro / prwatch-action

Github action for monitoring pull requests on a repository

prwatch-action [ archived ]

This repo is archived. The functionality it provides is largely provided by Github's new "real-time alerts". Go to https://github.com/settings/reminders and enable real-time alerts, and check "Your PR has merge conflicts". The code will remain on Github for future refernce.

A Github action for monitoring pull requests on a repository.

Supported features

• Monitor the mergeability of all open pull requests in your repository
• When pull requests have conflicts, comment on them and @mention the owner
• When pull requests have conflicts, transition them to new statuses, e.g. 'To Be Shipped' -> 'In Progress'
• Configure globally for the entire repository or on a per-user basis

Usage

To use this action, your Github Pull Requests must include in their description an associated issue tracker issue ID. E.g. if your Jira project name is FOO and the issue associated with your pull request is 1234, then your Pull Request must include FOO-1234 somewhere in its description.

Example Pull Request Description

This PR fixes the Thinger for FOO-1234

Setup

This action performs best when it is configured with settings.dual_pass.enabled and on.push to your mainline branch. The idea is to trigger a mergeability check when feature branches merge upstream. See the configuration section for how to enable dual-pass mode when triggering this action on.push.

1. Add ./.github/workflows/prwatch.yml workflow file to your repository Example Workflows
2. Add ./github-actions/prwatch-action/config.yaml to your repository. Example configuration

Run on Push

---
'on':
  push:
    branches:
      - master

name: PRWatch Action
jobs:
  check:
    name: Check Pull Requests
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Branch
        uses: actions/checkout@v1
      - name: Check for conflicts
        uses: acaloiaro/prwatch-action@latest
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}

Run every 15 minutes

---
'on':
  schedule:
    - cron: '*/15 * * * *'

name: PRWatch Action
jobs:
  check:
    name: Check Pull Requests
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Branch
        uses: actions/checkout@v1
      - name: Check for conflicts
        uses: acaloiaro/prwatch-action@latest
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}

Configuration File

This action is configured with a single yaml file. The configuration file lives in your repository at ./github-actions/prwatch-action/config.yaml. See examples for an example config.yaml.

User-specific settings are superseded by their global counterparts. i.e. if users.foobar.settings.issues.enable_transition is on for foobar, but off globally, the feature will be turned off for foobar.

If a global setting is unset globally, but on for a user, then it is still on for that user.

key	description	type	default
settings.dual_pass.enabled	Dual-pass mode allows this action to be triggered on 'push' to a target branch while allowing Github time to recalculate the mergeability of PRs	bool	true
settings.dual_pass.wait_duration	The duration of time to wait between the first and second pass in dual pass mode. This period of time should be long enough for Github to determine the mergeability of all your open pull requests. e.g. 1m30s. Note: The value of this variable must conform to the Golang duration format: https://golang.org/pkg/time/#ParseDuration	time	60s
settings.issues.enable_comment	When merge conflicts occurr, comment on associated issues	bool	true
settings.issues.enable_transition	When merge conflicts occur, transition associated issues to new status	bool	true
settings.issues.conflict_status	When merge conflicts occur, the new issue status to transitions issues to	string
settings.jira.enabled	Use Jira as your issue tracker	bool	true
settings.jira.host	The hostname of your Jira instance	string
settings.jira.project_name	The name of the Jira project associated with your repository	string
settings.jira.user	The "bot" user to use when transitioning and commenting on issues	string
users.<github_username>.settings.issues.enable_comment	Enable issue comments for a user	bool
users.<github_username>.settings.issues.enable_transition	Enable issue transitions for a user	bool

Secrets

GITHUB_TOKEN: It is not necessary to set this, as it is available to all Github Actions

JIRA_API_TOKEN: The access token associated with settings.jira.user.

prwatch-action's Issues

Add support for Github Projects/Issues

• Add support for Github projects
• When a new pull request is opened, add the PR to a Project
• Similar to Jira functionality, transition cards to new status when the underlying pull request of an issue goes into a conflict state.

Add support for custom merge drivers

Github does not support the use of custom merge drivers via .gitattributes. As a result, if custom merge drivers are specified for files in a project, then Github's CONFLICTING merge state can be inaccurate.

A solution to this problem is performing a merge attempt using a client that supports custom merge drivers via .gitattributes. One such client is https://github.com/libgit2/libgit2, which has go bindings https://github.com/libgit2/git2go.

Alternatively, we can shell out to a git binary on the system and attempt a merge using the CLI.

The end result should be a new IsConflicting that first checks whether a branch is CONFLICTING relative to its base, and subsequently checks whether the branch can be merged with its base by performing a merge (which is capable of using custom merge drivers).

Separate issue status transitions from issue comments

Currently, the transitioning of an issue's status and commenting on issues is coupled. Let's decouple these!

Fixed by: #23

Add support for issue names in branch names

Improve README.md

• Document that only Jira projects are supported (for now)
• Document how Pull Requests require a project key, e.g. MYPROJ-1234 anywhere in the description as a URL or plain text

Improve support for custom workflow statuses, in addition to built-in statuses

Support a user/team/global configuration

As a user --

• I want commenting enabled, but not status transitions

As a team --

• I want to be able to control all settings for every member of the team

As an org --

• I want to control everything for everyone

Global permissions supercede team-level permissions, and team-level permissions supercede user-level permissions.

Teams/users refer to Github users and teams.

For team settings --

• On boot, pull all members of team so PR authors' membership can be checked against team user lists.

This should be done through a new configuration YAML file.

settings:
  issue_transitions: 
    enabled: true 
  issue_comments:
    enabled: true
teams:
  - name: team 1
    settings:
      issue_transitions:
        enabled: false 
      issue_comments: 
        enabled: false
users:
  - user: acaloiaro
     settings:
       issue_transitions:
         enabled: false
       issue_comments: 
         enabled: true

Team-level permissions are a nice-to-have. Initially build out global and user-level perms.

Submit to https://github.com/sdras/awesome-actions

Consider replacing go binary with golang git library

See https://github.com/src-d/go-git

Support will need to be added for .gitattributes and the union merge driver https://github.com/src-d/go-git/blob/master/COMPATIBILITY.md

Add branding/add to "Marketplace"

Automatically rebase open pull requests

• Only when AUTO_REBASE: true env var set

Add dual-pass mode to better support event-based triggering

One of the current limitations of this Action is that it must be run on a schedule since it is impossible for Github to determine the mergability of pull requests against the branch on which the action is being triggered.

For example if the Action is configured as follows

---
'on':
  push:
    branches:
      - master

... 

then the mergability of any pull requests against master is not possible for Github to determine.

The problem is that running this action on a schedule can waste valuable Github-hosted Actions minutes. There are two approaches that would allow this Action to be run event-based rather than on a schedule.

1. Currently, the only Pull Requests placed under consideration by this action are those that are OPEN and have a Mergeable status of CONFLICTING. Instead of considering Github's Mergeable status at all, this action could rely on its own TryMerge functionality and ignore Github's mergeable state. The CONFLICTING check was how this Action originally worked, but #3 adds TryMerge support that, in some ways, deprecates Github's mergeable state check.
2. A two-phase approach where the first pass of pulling down OPEN pull requests will return a list of pull requests with unknown mergeable state; wait some amount of time (30s?), and then pull down the OPEN pull requests list a second time and they should have an updated mergeable state.

I'm leaning toward (1.).

Templateize issue comments using Go's template engine.

• Expose variable for settings comment tamplates
• Document template variables available

Add support for Github "checks"

• Perform some operations when a pull request has failed checks
• Consider what is a reasonable interface for expressing "operations"