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.
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!
Top comments (0)