Automate pull requests with GitHub Starter Workflows

13th October 2022 ・ By Marcelo Sousa ・

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:

Add the Reviewpad configuration with the specification of the automations
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:

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

These can be configured in Reviewpad in a few minutes.

1api-version: reviewpad.com/v3.x
2
3labels:
4  small:
5    color: "#294b69"
6  medium:
7    color: "#a8c3f7"
8  large:
9    color: "#8a2138"
10
11workflows:
12  - name: add-label-with-size
13    always-run: true
14    if:
15      - rule: $size() <= 30
16        extra-actions:
17          - '$addLabel("small")'
18      - rule: $size() > 30 && $size() <= 100
19        extra-actions:
20          - '$addLabel("medium")'
21      - rule: $size() > 100
22        extra-actions:
23          - '$addLabel("large")'
24
25  - name: lint-commits
26    always-run: true
27    if:
28      - rule: '!$hasLinearHistory()'
29        extra-actions:
30          - '$warn($sprintf("The pull request it outdated with the base @%v", $base()))'
31          - '$fail("Pull request is outdated")'
32      - rule: 'true'
33        extra-actions:
34          - '$commitLint()'
35          - '$titleLint()'
36
37  - name: check-for-linked-issued
38    always-run: true
39    if:
40      - '!$hasLinkedIssues()'
41    then:
42      - '$info("This pull request does not have a linked issue")'
43
44  - name: first-time-contributor
45    always-run: true
46    if:
47      - '$pullRequestCountBy($author(), "all") == 1'
48    then:
49      - '$commentOnce($sprintf("Welcome @%v! Thank you so much for your first pull request!", [$author()]))'
50
51  - name: empty-description
52    always-run: true
53    if:
54      - $description() == ""
55    then:
56      - '$warn("The description is empty. Please add more information!")'
57      - '$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 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.

1name: Reviewpad
2
3on: 
4  pull_request_target:
5    types:
6      - opened
7      - synchronize
8      - edited
9
10jobs:
11  reviewpad_job:
12    runs-on: ubuntu-latest
13    name: Reviewpad
14    steps:
15      - name: Reviewpad
16        uses: reviewpad/action@v3.x
17        with:
18          # Uses a default Reviewpad configuration file to get your started.
19          # For customization and documentation, see https://github.com/reviewpad/action
20          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.

1{
2    "name": "Reviewpad Starter Workflow",
3    "description": "Reviewpad starter workflow.",
4    "iconName": "reviewpad-icon"
5}

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

The Demo

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 Reviewpad App.

PS: Support our project on GitHub with a star!