action-jira-linter 🧹

A light-weight lint workflow to unite the worlds of GitHub and Jira. Based on the fine work of ClearTax on jira-lint.

---

• action-jira-linter 🧹
  • Installation
  • Features
    • PR Status Checks
    • PR Description & Labels
      • Description
      • Labels
      • Issue Status Validation
      • Soft-validations via comments
    • Options
    • Skipping branches
  • Contributing
  • FAQ
  • Contributors

Installation

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

name: action-jira-linter
on: [pull_request]

jobs:
  action-jira-linter:
    runs-on: ubuntu-latest
    steps:
      - uses: btwrk/[email protected]
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          jira-token: ${{ secrets.JIRA_TOKEN }}
          jira-base-url: https://your-domain.atlassian.net

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

Features

PR Status Checks

action-jira-linter 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, action-jira-linter 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, status and labels and add them to the PR description.

Labels

action-jira-linter 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 Status Validation

Issue status is shown in the Description.

Why validate issue status? In some cases, one may be pushing changes for a story that is set to Done/Completed or it may not have been pulled into working backlog or current sprint.

This option allows discouraging pushing to branches for stories that are set to statuses other than the ones allowed in the project; for example - you may want to only allow PRs for stories that are in To Do/Planning/In Progress states.

The following flags can be used to validate issue status:

• validate-issue-status
  • If set to true, action-jira-linter will validate the issue status based on allowed-issue-statuses
• allowed-issue-statuses
  • This will only be used when validate-issue-status is true. This should be a comma separated list of statuses. If the detected issue's status is not in one of the allowed-issue-statuses then action-jira-linter will fail the status check.

Example of invalid status

<p>:broken_heart: The detected issue is not in one of the allowed statuses :broken_heart:</p>
<table>
  <tr>
    <th>Detected Status</th>
    <td>${issueStatus}</td>
    <td>:x:</td>
  </tr>
  <tr>
    <th>Allowed Statuses</th>
    <td>${allowedStatuses}</td>
    <td>:heavy_check_mark:</td>
  </tr>
</table>
<p>Please ensure your jira story is in one of the allowed statuses</p>

Soft-validations via comments

action-jira-linter 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

A full example with all available options and example values is provided below.

- uses: btwrk/[email protected]
  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
    validate-issue-status: true
    allowed-issue-statuses: |
      To Do
      In Progress
      Done
    fail-on-error: false
    ignored-label-types: |
      project
      hotfix
      type
    details-open: false

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.	x	null
jira-token	Token used to fetch Jira Issue information. Check below for more details on how to generate the token.	x	null
jira-base-url	The subdomain of JIRA cloud that you use to access it. Ex: https://your-domain.atlassian.net.	x	null
skip-branches	A regex to ignore running action-jira-linter on certain branches, like production etc.		''
skip-comments	A Boolean if set to true then action-jira-linter will skip adding lint comments for PR title.		false
pr-threshold	An Integer based on which action-jira-linter will add a comment discouraging huge PRs.		800
validate-issue-status	A Boolean based on which action-jira-linter will validate the status of the detected jira issue		false
allowed-issue-statuses	A line-separated list of acceptable Jira issue statuses. The detected jira issue's status will be compared against this list and if a match is not found then the status check will fail. Note: Requires validate-issue-status to be set to true.		'In Progress'
fail-on-error	A Boolean which, if set to true, fails the GitHub Action when an error occurs. Default true.		false
ignored-label-types	A list of label types to ignore. Valid values: project, hotfix, type.		''
details-open		Open the ticket details table by default.	true

Special note on jira-token: Since tokens are private, we suggest adding them as GitHub secrets.

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

1. Generate an API token via JIRA.
2. Add the generated token as the secret JIRA_TOKEN in your GitHub project.

Note: The user needs to 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.

action-jira-linter 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 💻

Asbjørn Ulsberg 💻

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