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.
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: 1000It can also be used as part of an existing workflow by adding it as a step. More information about the options here.
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
# ...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.
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, status and labels and add them to the PR description.
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
Escherthen it will addescheras a label. HOTFIX-PROD- if the PR is raised againstproduction-release.HOTFIX-PRE-PROD- if the PR is raised againstrelease/v*.- Jira issue type (based on your project).
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,jira-lintwill validate the issue status based onallowed_issue_statuses
- If set to
allowed_issue_statuses- This will only be used when
validate_issue_statusistrue. This should be a comma separated list of statuses. If the detected issue's status is not in one of theallowed_issue_statusesthenjira-lintwill fail the status check.
- This will only be used when
Example of invalid status
💔 The detected issue is not in one of the allowed statuses 💔
| Detected Status | ${issueStatus} | ❌ |
|---|---|---|
| Allowed Statuses | ${allowedStatuses} | ✔️ |
Please ensure your jira story is in one of the allowed statuses
jira-lint will add comments to a PR to encourage better PR practices:
A good PR title
A comment discouraging PRs which are too large (based on number of lines of code changed).
| 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 |
validate_issue_status |
A Boolean based on which jira-lint will validate the status of the detected jira issue |
false | false |
allowed_issue_statuses |
A comma separated list of allowed 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. |
false | "In Progress" |
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:-
- Generate an API token via JIRA
- Create the encoded token in the format of
base64Encode(<username>:<api_token>). For example, if the username is[email protected]and the token is954c38744be9407ab6fb, then[email protected]:954c38744be9407ab6fbneeds to be base64 encoded to formY2lAZXhhbXBsZS5jb206OTU0YzM4NzQ0YmU5NDA3YWI2ZmI= - The above value (in this example
Y2lAZXhhbXBsZS5jb206OTU0YzM4NzQ0YmU5NDA3YWI2ZmI=) needs to be added as theJIRA_TOKENsecret in your GitHub project.
Note: The user should have the required permissions (mentioned under GET Issue).
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.
Follow the instructions here to know more about GitHub actions.
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 🙅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!