Automate pull requests with GitHub Starter Workflows

This guide shows how you can set up GitHub workflow templates to automate common GitHub pull requests workflows!

The Problem

Every time a new repository is created in our GitHub organization, we need to ensure that it starts with a set of common pull request automations.

In the past, this meant that we needed to install multiple GitHub actions.

We were copying the GitHub action YML configurations from other repositories and then customizing it for the newly created repository.

This process was fine but it is error-prone and not very scalable because we need to maintain and customize multiple GitHub actions.

The Solution

Many GitHub repositories already use the .github folder to host workflows and templates for pull requests.

GitHub provides the ability to share the files across all the repositories in an organization in the special .github repository.

This means that we can create a .github repository in our organization and then add the GitHub actions that we want to share across all the repositories.

GitHub calls these starter workflows.
A starter workflow could be used to easily add workflows to the newly created projects.

This solves our problem of copying YML configurations between repositories but we need to create one starter workflow for each pull request automation.

So, we've decided to use Reviewpad as a single source of truth for all the pull request automations.

This way, any repository can get these automations with a couple of clicks.

The Setup

We will use Reviewpad to show case starter workflows.

To do that, we will need two steps:

1. Add the Reviewpad configuration with the specification of the automations
2. Add the Reviewpad starter workflow to the .github repository.

Step 1. Specify the pull request automations in Reviewpad

We started with the following list of automations and checks:

1. Label pull requests based on their size
2. Check that the pull request commits come after one another (i.e. they have a linear history)
3. Check the commits messages against the conventional commits specification
4. Check the pull request title against the conventional commits specification (this makes sense because we squash and merge certain pull requests)
5. Warn pull requests that do not have an associated GitHub issue
6. Add a comment to pull requests if their description was empty
7. Greet users on their first pull request

These can be configured in Reviewpad in a few minutes.

api-version: reviewpad.com/v3.x

labels:
  small:
    color: "#294b69"
  medium:
    color: "#a8c3f7"
  large:
    color: "#8a2138"

workflows:
  - name: add-label-with-size
    always-run: true
    if:
      - rule: $size() <= 30
        extra-actions:
          - '$addLabel("small")'
      - rule: $size() > 30 && $size() <= 100
        extra-actions:
          - '$addLabel("medium")'
      - rule: $size() > 100
        extra-actions:
          - '$addLabel("large")'

  - name: lint-commits
    always-run: true
    if:
      - rule: '!$hasLinearHistory()'
        extra-actions:
          - '$warn($sprintf("The pull request it outdated with the base @%v", $base()))'
          - '$fail("Pull request is outdated")'
      - rule: 'true'
        extra-actions:
          - '$commitLint()'
          - '$titleLint()'

  - name: check-for-linked-issued
    always-run: true
    if:
      - '!$hasLinkedIssues()'
    then:
      - '$info("This pull request does not have a linked issue")'

  - name: first-time-contributor
    always-run: true
    if:
      - '$pullRequestCountBy($author(), "all") == 1'
    then:
      - '$commentOnce($sprintf("Welcome @%v! Thank you so much for your first pull request!", [$author()]))'

  - name: empty-description
    always-run: true
    if:
      - $description() == ""
    then:
      - '$warn("The description is empty. Please add more information!")'
      - '$fail("Empty description")'

Add this file to your organization .github repository so that it can be referenced later in the Reviewpad GitHub action.

For more information about the Reviewpad configuration, check our documentation.

Step 2. Add the Reviewpad starter workflow to the .github repository

The Reviewpad starter workflow is a GitHub action that will run Reviewpad as a GitHub action on every pull request.

To add a starter workflow, you need to add two files to the .github repository under the folder workflow-templates.

The first file reviewpad_action.yml is the Reviewpad GitHub action that will be installed in the repositories.

name: Reviewpad

on: 
  pull_request_target:
    types:
      - opened
      - synchronize
      - edited

jobs:
  reviewpad_job:
    runs-on: ubuntu-latest
    name: Reviewpad
    steps:
      - name: Reviewpad
        uses: reviewpad/action@v3.x
        with:
          # Uses a default Reviewpad configuration file to get your started.
          # For customization and documentation, see https://github.com/reviewpad/action
          file_url: [URL-TO-REVIEWPAD-CONFIGURATION]

Note that you should update file_url parameter to point to your organization configuration file.

The second file reviewpad_action.properties.json is the metadata file that specifies the starter workflow.

{
    "name": "Reviewpad Starter Workflow",
    "description": "Reviewpad starter workflow.",
    "iconName": "reviewpad-icon"
}

If you want to add the Reviewpad logo to the starter workflow, add the icon to that folder.

The Demo

You can check the demo in the original post on Reviewpad's blog here!

If you liked this post, join our community on Discord to keep learning new ways to save time in pull requests.

And, if you to get more features out of Reviewpad consider installing the GitHub Reviewpad App.

PS: Support our project on GitHub with a star!