Automatically Add Links to Your Pull Request Description

How much time do you spend adding JIRA or any other external links to your Pull Request description? If you raise five Pull Requests a week and it takes you about 10 seconds to grab and insert that link, you spend 43 minutes a year copying and pasting links to GitHub.

But that’s not the worst part, the cognitive cost of jumping between tools and tasks affects your productivity beyond those 10 seconds.

Wouldn’t it be cool if you could spend your time and focus doing more important things? This is why I created pullrequestbadge.com.

Bash scripting

I wanted to automate this process. Therefore I wrote a bash script that takes the JIRA number from the current branch name and generates markdown.

I shared this script with my colleagues and many of them added JIRA links using it. Seeing this initial success encouraged me to invest more time in the idea. The script was a step in the right direction, but it still required people to paste the generated markdown.

GitHub App

Then in summer 2019, I started working on porting this bash script to a GitHub app just for fun and the following advantages of such a GitHub App:

• No bash script required
• It can be easily added to any repositories.
• Works out of the box if the branch name or the Pull Request title includes a JIRA ticket number

A few evenings passed by and on Thursday evening the app was able to handle the first request. Everything was still hardcoded, but it was a great moment. Motivated by this win I kept on coding and a few days later I installed the GitHub app in one of our main repositories.

We don’t enforce a specific format for branch names, but it’s common to include the JIRA ticket number in the branch name so it worked great for everyone. No more copying & pasting links, it just works.

Linking beyond JIRA

Linking to JIRA automatically is great, but there’s much more we can do. Every Pull Request gets deployed to a preview instance that stays updated with the changes we made. Each deployment gets its own fixed URL like https://pr-123.app.company.com. This link is added to the Pull Request using GitHub's Deployment API.

Reaching for this link can be tricky with all the other activities on your Pull Request like comments. Wouldn’t it be helpful to add a link to the Pull Request description? Automatically, of course.

Thanks to the flexibility of Pull Request Badge, we can link to anything based on information provided by GitHub such as the Pull Request number.

The config to produce those badges is quite simple and is stored .github/pr-badge.yml within your repository.

- url: "https://jira.company.com/jira/browse/$issuePrefix"
  label: "JIRA"
  color: "0052CC"
  when: "$issuePrefix"

- url: "https://pr-$prNumber.app.company.com/"
  message: "Preview"
  color: "green"

Check out the example section for more inspiration.

GitHub Universe 2019

As usual, I followed along with GitHub’s latest announcements, and all of sudden they came up with autolink references which does basically the same as Pull Request Badge.

But there a few key differences:

• Unlike GitHub’s solution, the Pull Request Badge config is part of your repository
• No need to maintain mapping for each JIRA project
• Links are presented in a consistent way above your Pull Request description
• Doesn’t require any effort besides including the JIRA ticket number in the branch name
• Fully configurable to link to any external system
• Badges are customizable in appearance/look and feel
• Access to the raw Pull Request webhook event with endless possibilities.
• Conditional links

Give Pull Request Badge a try

Installing the app doesn’t cost you anything. During the public beta public and private repositories are supported. Install Pull Request Badge.

What the testimonials say

»With the Pull Request Badge App developers have everything they need to move forward and this helps us to make our communication much more effective.«

Markus Staab

Team Lead at Complex GmbH & Co. KG

»With a large distributed engineering team, it can be hard to enforce rules about including links to tickets within Pull Requests; having it automated was the perfect solution and it’s super slick.«

Alastair Lockie

JavaScript Engineer at Brandwatch

»As engineers we use GitHub heavily every day. We just as often need to interface with other systems or resources such as Atlassian Jira or deployment previews. Pull Request Badge helps us bridging the gaps and linking to anything external becomes a breeze.«

Tobias Deekens

Software Engineer at commercetools GmbH

Wrap-up

This Pull Request Badge app has really helped me and many others to not have to think about adding links to the Pull Request description anymore. It provides a consistent way to represent such meta information and as shown is not limited to a single use case.