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.
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.
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.
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
- 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.«
»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.«
»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.«
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.