Pull Request Badge

Add context to your pull request descriptions

Pull Request Badge lets you programmatically insert badges in your pull request descriptions and then link them to anything. Like this one 👇

Pull Request Badge preview
Live demo

How it works

After installation, Pull Request Badge will receive a webhook event whenever a Pull Request is opened or edited. Based on the configuration file in your repository, badges that match criteria will be inserted at the beginning of the Pull Request description.

I initially created Pull Request Badge to deal with JIRA links, but it can easily present any kind of information through the simple and flexible API. For example: how about adding a preview badge with a link to a preview instance? Or indicate if the Pull Request is rather large? Check out the $payload attribute for more details. Your creativity is the limit.

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. Read the story behind Pull Request Badge on my blog.

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.

Setup

  • Sign into GitHub and visit our Marketplace listing.
  • Choose a plan and setup 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 Tweak login page"
your-repo/.github/pr-badge.yml
Edit
1
2
3
4
5
- label: "JIRA"
  message: "$issuePrefix"
  color: "#0052CC"
  url: "https://jira.company.com/browse/$issuePrefix"
  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. The default value is #0052CC

imageUrl string

The URL of the image.

when string

JavaScript code that must be an expression (something which evaluates to a boolean). Example: $additions > 200

Examples

Preview
Edit
1
2
3
4
- label: "Preview"
  message: "PR $prNumber"
  color: "blue"
  url: "https://pr-$prNumber.company.com"
Size
Edit
1
2
3
4
- label: "PR Size"
  message: "Large"
  color: "red"
  when: "$additions > 200"
Webhook
Edit
1
2
- message: "$payload.pull_request.user.login"
  color: "green"

Variables

$payload object

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

$prNumber int

The number of this Pull Request.

Shorthand for: $payload.pull_request.number

$branchName string

The name of the branch where your changes are implemented.

Shorthand for: $payload.pull_request.head.ref

$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.

Shorthand for: $payload.pull_request.user.login

$isDraft boolean

Indicates whether this Pull Request is a draft.

Shorthand for: $payload.pull_request.draft

$additions int

The number of additions made in this Pull Request

Shorthand for: $payload.pull_request.additions

$deletions int

The number of deletions made in this Pull Request

Shorthand for: $payload.pull_request.deletions

$commits int

Total number of commits

Shorthand for: $payload.pull_request.commits

$changedFiles int

Total number of changed files

Shorthand for: $payload.pull_request.changed_files

$owner string

Name of the repository owner

Shorthand for: $payload.repository.owner.login

$repo string

Name of the repository

Shorthand for: $payload.repository.name

$slug string

The repository slug eg. Codertocat/Hello-World

Shorthand for: $payload.repository.full_name

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

FAQ

Required GitHub permissions

Pull Request Badge requires the following GitHub permissions:

  • Read access to files located at .github/pr-badge.yml.

    This file contains the configuration for Pull Request Badge. We cannot read or write any source code!

  • Read access to metadata.

    All GitHub Apps require the Metadata permission. The metadata permission provides access to a collection of read-only endpoints with metadata for various resources. These endpoints do not leak sensitive private repository information.

  • Read and write access to pull requests.

    We use the Pull Requests permission to listen for new Pull Requests required to update the pull request descritpon with badges.

Is it Open Source?

No, not yet. The source code is exclusively available to people who sponsor me on GitHub, but after reaching a certain number of sponsors, the software fully open-source and available to anyone.

Do you support private repositories?

Yes, we do. Check out our plans for details on private GitHub repositories.

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.

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

Questions?

If you have any questions or comments please do not hesitate to concat me. hello@pullrequestbadge.com or send me a DM on Twitter.