Automate pull requests with GitHub Starter Workflows
Tags: github, devops, codereview, programming
Published: 2022-10-27 21:24:41

_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](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization).
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](https://reviewpad.com) 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](https://www.conventionalcommits.org/)
4. Check the pull request title against the [conventional commits specification](https://www.conventionalcommits.org/) (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. 

```yaml
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](https://docs.reviewpad.com/guides/syntax).


### 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](https://github.com/reviewpad/.github/blob/main/workflow-templates/reviewpad_action.yml) is the Reviewpad GitHub action that will be installed in the repositories.

```yml
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](https://github.com/reviewpad/.github/blob/main/workflow-templates/reviewpad_action.yml#L21) to point to your organization configuration file.


The second file [reviewpad_action.properties.json](https://github.com/reviewpad/.github/blob/main/workflow-templates/reviewpad_action.properties.json) is the metadata file that specifies the starter workflow. 

```json
{
    "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](https://github.com/reviewpad/.github/blob/main/workflow-templates/reviewpad-icon.svg) to that folder.

## The Demo

You can check the demo in the original post on Reviewpad's blog [here](https://reviewpad.com/blog/automate-pull-requests-in-one-minute)!

<br/>

If you liked this post, join our community on [Discord](https://reviewpad.com/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](https://docs.reviewpad.com/getting-started/installation).

PS: Support our project on [GitHub](https://github.com/reviewpad/reviewpad) with a star!