Badges for your Pull Request

Badges are a unified way to present meta information and widely adopted in the software community. This GitHub App brings badges to your Pull Requests in an automated way. The root idea was to automatically add a JIRA badge whenever a Pull Request is opened, but it's not limited to that.

stefanbuck• edited by pull-request-badgebot

How it works

Whenever a Pull Request is opened and the branch name or the Pull Request title matches the naming convention, this GitHub app will automatically add a badge at the beginning of the Pull Request description. This includes a link referencing the JIRA ticket.

Pull Request Badge is not limited to JIRA! Through the simple API you can easily present any kind of information. How about adding a preview badge with a link to a preview instance? Or indicate if the Pull Request is small? Check out the $payload attribute for more details. Your creativity is the limit.

»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

Setup

  • Install the app
  • Create a .github/pr-badge.yml file in your repository with the following content.
  • Create a Pull Request where the title starts with a JIRA prefix like: "CORE-123 Badges everywhere"
your-repo/.github/pr-badge.yml
1
2
3
4
5
label: "JIRA"
url: "https://jira.company.com/browse/$issuePrefix"
message: "$issuePrefix"
color: "0052CC"
when: "$issuePrefix"

Attributes

label string

Text on the left side of the badge.

message string

Text on the right side of the badge.

url string

If added, the badge will be wrapped with this URL.

color string

The color for the badge in hex format without #. The default value is 0052CC

when string

JavaScript code that must be an expression (something which evaluates to a boolean).

Examples

Preview
1
2
3
4
label: "Preview"
url: "https://$prNumber.preview.company.com/"
message: "Available"
color: "green"
Size
1
2
3
4
label: "Size"
message: "Large PR"
color: "red"
when: "$additions > 500 || $deletions > 500"
Label
1
2
3
message: "Work in Progress"
color: "yellow"
when: "$labels.includes('WIP')"
Static
1
2
3
4
5
- label: "Hello"
  message: "World"
- label: "Foo"
  message: "Bar"
  color: "green"
Webhook payload
1
2
label: "User"
message: "$payload.pull_request.header.user.login"
»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

Variables

$prNumber int

The number of this Pull Request.

$branchName string

The name of the branch where your changes are implemented.

$issuePrefix string

The branch name or Pull Request title issue prefix extracted when following the Naming Convention.

$author string

Name of the Pull Request author.

$isDraft boolean

Indicates whether this Pull Request is a draft.

$additions int

The number of additions made in this Pull Request

$deletions int

The number of deletions made in this Pull Request

$commits int

Total number of commits

$changedFiles int

Total number of changed files

$payload object

Raw webhook payload object from GitHub. Check out the webhook payload example for further information.

Naming convention

Pull Request Badge uses the following naming convention to extract the $issuePrefix. Please make sure your branch name or Pull Request title contains an uppercase issuePrefix.

Branch names

  • ABC-123
  • ABC-123-better-accessibility
  • foo/ABC-123
  • foo/ABC-123-better-accessibility

Pull Request titles

  • ABC-123
  • ABC-123 Better accessibility
  • foo/ABC-123
  • foo/ABC-123 Better accessibility
»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

FAQ

Is it Open Source?

No, not yet. The source code is exclusively available to people who sponsor me on GitHut, but after reaching a certain number of sponsors, the software fully open-source and available to anyone. Head over to github.com/stefanbuck/pull-request-badge-app to learn more about it.

GitHub Permissions

We only request necessary GitHub permission and we canot read or write any source code! The Pull Request App requires the following GitHub Permissions:

  • Read access to files located at .github/pr-badge.yml
  • Read access to metadata
  • Read and write access to pull requests

Self hosting & GitHub Enterprise

Become a sponsorware "customer" and you will get access to the source code which then allows you to run the app yourself.

Brought to you by

Stefan Buck

Hello there! I'm Stefan 👋. I care a lot about efficiency and that's the reason I built a browser extension that allows you to navigate through code on GitHub much more efficiently. OctoLinker is trusted by over 25,000 developers and my most favored side project in the past five years.

This is just the beginning! I have plenty other ideas on how to make your developer experience much better. Sign up to be the first to hear about other tools I'm working on.