Skip to content

A light-weight lint workflow when using GitHub along with JIRA for project management

License

Notifications You must be signed in to change notification settings

hyperoslo/jira-lint

 
 

Repository files navigation

jira-lint 🧹

A light-weight lint workflow when using GitHub along with JIRA for project management. Ported from pivotal-lint for similar usage with Atlassian's Jira Software.

GitHub package.json version GitHub All Contributors build & test


Installation

To make jira-lint a part of your workflow, just add a jira-lint.yml file in your .github/workflows/ directory in your GitHub repository.

name: jira-lint
on: [pull_request]

jobs:
  jira-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: cleartax/jira-lint@master
        name: jira-lint
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          jira-token: ${{ secrets.JIRA_TOKEN }}
          jira-base-url: https://your-domain.atlassian.net
          skip-branches: '^(production-release|master|release\/v\d+)$'
          skip-comments: true
          pr-threshold: 1000

It can also be used as part of an existing workflow by adding it as a step. More information about the options here.

Semantic Versions

If you want more stability in versions of jira-lint than @master you can also use the semantic releases for jira-lint.

Example:

# ...
steps:
  - uses: cleartax/[email protected]
    name: jira-lint
    # ...

Features

PR Status Checks

jira-lint adds a status check which helps you avoid merging PRs which are missing a valid Jira Issue Key in the branch name. It will use the Jira API to validate a given key.

PR Description & Labels

Description

When a PR passes the above check, jira-lint will also add the issue details to the top of the PR description. It will pick details such as the Issue summary, type, estimation points and labels and add them to the PR description.

Labels

jira-lint will automatically label PRs with:

  • A label based on the Jira Project name (the project the issue belongs to). For example, if your project name is Escher then it will add escher as a label.
  • HOTFIX-PROD - if the PR is raised against production-release.
  • HOTFIX-PRE-PROD - if the PR is raised against release/v*.
  • Jira issue type (based on your project).

Issue details and labels added to a PR

Issue details and labels added to a PR.

Soft-validations via comments

jira-lint will add comments to a PR to encourage better PR practices:

A good PR title

When the title of the PR matches the summary/title of the issue well.

When the title of the PR is slightly different compared to the summary/title of the issue

When the title of the PR is very different compared to the summary/title of the issue

A comment discouraging PRs which are too large (based on number of lines of code changed).

Batman says no large PRs 🦇

Options

key description required default
github-token Token used to update PR description. GITHUB_TOKEN is already available when you use GitHub actions, so all that is required is to pass it as a param here. true null
jira-token Token used to fetch Jira Issue information. Check below for more details on how to generate the token. true null
jira-base-url The subdomain of JIRA cloud that you use to access it. Ex: "https://your-domain.atlassian.net". true null
skip-branches A regex to ignore running jira-lint on certain branches, like production etc. false ' '
skip-comments A Boolean if set to true then jira-lint will skip adding lint comments for PR title. false false
pr-threshold An Integer based on which jira-lint will add a comment discouraging huge PRs. false 800

Since tokens are private, we suggest adding them as GitHub secrets.

jira-token

The Jira token is used to fetch issue information via the Jira REST API. To get the token:-

  1. Generate an API token via JIRA
  2. Create the encoded token in the format of base64Encode(<username>:<api_token>). For example, if the username is [email protected] and the token is 954c38744be9407ab6fb, then [email protected]:954c38744be9407ab6fb needs to be base64 encoded to form Y2lAZXhhbXBsZS5jb206OTU0YzM4NzQ0YmU5NDA3YWI2ZmI=
  3. The above value (in this example Y2lAZXhhbXBsZS5jb206OTU0YzM4NzQ0YmU5NDA3YWI2ZmI=) needs to be added as the JIRA_TOKEN secret in your GitHub project.

Note: The user should have the required permissions (mentioned under GET Issue).

Skipping branches

Since GitHub actions take string inputs, skip-branches must be a regex which will work for all sets of branches you want to ignore. This is useful for merging protected/default branches into other branches. Check out some examples in the tests.

jira-lint already skips PRs which are filed by bots (for eg. dependabot). You can add more bots to this list, or add the branch-format followed by the bot PRs to the skip-branches option.

Contributing

Follow the instructions here to know more about GitHub actions.

FAQ

Why is a Jira key required in the branch names?

The key is required in order to:

  • Automate change-logs and release notes ⚙️.
  • Automate alerts to QA/Product teams and other external stake-holders 🔊.
  • Help us retrospect the sprint progress 📈.
Is there a way to get around this? Nope 🙅

Contributors

Thanks goes to these wonderful people (emoji key):


Raj Anand

💻 👀 🤔

Aditi Mohanty

💻 📖 🚇

Dustin Row

👀

richardlhao

💻

Nimesh Manmohanlal

📖

Lewis Waddicor

💻

This project follows the all-contributors specification. Contributions of any kind welcome!

About

A light-weight lint workflow when using GitHub along with JIRA for project management

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 88.8%
  • JavaScript 10.0%
  • Shell 1.2%