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.

Badge that links to JIRA
Badge that links to JIRA

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.

GitHub deployment
GitHub deployment

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.

Bages added via GitHub App
Bages added via GitHub App

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"
GitHub app config

Check out the example section for more inspiration.

I have plenty other ideas on how to improve your developer experience. Be the first to hear about new developer tools I'm working on.
I promise to never sell your email address or spam you, and you can unsubscribe at any time.

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
  • The self-hosted version available through Sponsorewares

What is Sponsorware?

Sponsorware means building and releasing a project exclusively to people who sponsor me on GitHub, but after reaching a certain number of sponsors, make the package fully open-source and available to anyone. Head over to https://github.com/stefanbuck/pull-request-badge-app to learn more about it.

Want to try it out?

Access is free for public repositories. To unlock private repositories as well as the option to host the app yourself you need to become a Sponsorware supporter.

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
Markus Staab
»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
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
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.

Stefan Buck
Written by
Stefan Buck is a Staff Software Engineer. In 2013, he created OctoLinker, a browser extension for GitHub trusted and used by over 25,000 developers. Recently he started Pull Request Badge, a GitHub App that brings badges to your Pull Request.