{"id":14156683,"url":"https://github.com/ClearTax/jira-lint","last_synced_at":"2025-08-06T03:31:11.578Z","repository":{"id":43874508,"uuid":"238172283","full_name":"ClearTax/jira-lint","owner":"ClearTax","description":"A light-weight lint workflow when using GitHub along with JIRA for project management","archived":false,"fork":false,"pushed_at":"2024-08-12T03:40:12.000Z","size":461,"stargazers_count":58,"open_issues_count":27,"forks_count":60,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-11-18T20:54:04.282Z","etag":null,"topics":["jira","jira-issue","labels","pr-description","prs","workflow"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ClearTax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-04T09:49:24.000Z","updated_at":"2024-06-17T20:38:00.000Z","dependencies_parsed_at":"2024-08-17T08:18:06.394Z","dependency_job_id":null,"html_url":"https://github.com/ClearTax/jira-lint","commit_stats":{"total_commits":22,"total_committers":7,"mean_commits":3.142857142857143,"dds":0.5909090909090908,"last_synced_commit":"0b90e54c614ba320d44d4d2b02df4c0c7fa70f89"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":"actions/typescript-action","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClearTax%2Fjira-lint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClearTax%2Fjira-lint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClearTax%2Fjira-lint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClearTax%2Fjira-lint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ClearTax","download_url":"https://codeload.github.com/ClearTax/jira-lint/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228835541,"owners_count":17979163,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jira","jira-issue","labels","pr-description","prs","workflow"],"created_at":"2024-08-17T08:07:59.915Z","updated_at":"2024-12-09T04:30:48.444Z","avatar_url":"https://github.com/ClearTax.png","language":"TypeScript","funding_links":[],"categories":["workflow"],"sub_categories":[],"readme":"# jira-lint ๐Ÿงน\n\n\u003e A light-weight lint workflow when using GitHub along with [JIRA][jira] for project management.\n\u003e Ported from [pivotal-lint](https://github.com/ClearTax/pivotal-lint/) for similar usage with Atlassian's Jira Software.\n\n![GitHub package.json version](https://img.shields.io/github/package-json/v/cleartax/jira-lint?style=flat-square)\n[![GitHub](https://img.shields.io/github/license/cleartax/jira-lint?style=flat-square)](https://github.com/cleartax/jira-lint/blob/master/LICENSE.md)\n[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors)\n![build \u0026 test](https://github.com/ClearTax/jira-lint/workflows/lint,%20build%20\u0026%20test/badge.svg)\n\n---\n\n\u003c!-- toc --\u003e\n\n- [Installation](#installation)\n - [Semantic Versions](#semantic-versions)\n- [Features](#features)\n - [PR Status Checks](#pr-status-checks)\n - [PR Description \u0026 Labels](#pr-description--labels)\n - [Description](#description)\n - [Labels](#labels)\n - [Soft-validations via comments](#soft-validations-via-comments)\n - [Options](#options)\n - [`jira-token`](#jira-token)\n - [Skipping branches](#skipping-branches)\n- [Contributing](#contributing)\n- [FAQ](#faq)\n- [Contributors](#contributors)\n\n\u003c!-- tocstop --\u003e\n\n## Installation\n\nTo make `jira-lint` a part of your workflow, just add a `jira-lint.yml` file in your `.github/workflows/` directory in your GitHub repository.\n\n```yml\nname: jira-lint\non: [pull_request]\n\njobs:\n jira-lint:\n runs-on: ubuntu-latest\n steps:\n - uses: cleartax/jira-lint@master\n name: jira-lint\n with:\n github-token: ${{ secrets.GITHUB_TOKEN }}\n jira-token: ${{ secrets.JIRA_TOKEN }}\n jira-base-url: https://your-domain.atlassian.net\n skip-branches: '^(production-release|master|release\\/v\\d+)$'\n skip-comments: true\n pr-threshold: 1000\n```\n\nIt can also be used as part of an existing workflow by adding it as a step. More information about the [options here](#options).\n\n### Semantic Versions\n\nIf you want more stability in versions of `jira-lint` than `@master` you can also use the [semantic releases for jira-lint](https://github.com/cleartax/jira-lint/releases).\n\nExample:\n\n```yaml\n# ...\nsteps:\n - uses: cleartax/jira-lint@v0.0.1\n name: jira-lint\n # ...\n```\n\n## Features\n\n### PR Status Checks\n\n`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](https://developer.atlassian.com/cloud/jira/platform/rest/v3/) to validate a given key.\n\n### PR Description \u0026 Labels\n\n#### Description\n\nWhen 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.\n\n#### Labels\n\n`jira-lint` will automatically label PRs with:\n\n- 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.\n- `HOTFIX-PROD` - if the PR is raised against `production-release`.\n- `HOTFIX-PRE-PROD` - if the PR is raised against `release/v*`.\n- Jira issue type ([based on your project](https://confluence.atlassian.com/adminjiracloud/issue-types-844500742.html)).\n\n\u003cfigure\u003e\n \u003cimg src=\"https://assets1.cleartax-cdn.com/cleargst-frontend/misc/1580891341_jira_lint.png\" alt=\"Issue details and labels added to a PR\" /\u003e\n \u003cfigcaption\u003e\n Issue details and labels added to a PR.\n \u003c/figcaption\u003e\n\u003c/figure\u003e\n\n#### Issue Status Validation\nIssue status is shown in the [Description](#description).\n**Why validate issue status?** \nIn 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.\n\n 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.\n\nThe following flags can be used to validate issue status:\n- `validate_issue_status`\n - If set to `true`, `jira-lint` will validate the issue status based on `allowed_issue_statuses`\n- `allowed_issue_statuses`\n - 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 `jira-lint` will fail the status check.\n\n**Example of invalid status**\n \u003cp\u003e:broken_heart: The detected issue is not in one of the allowed statuses :broken_heart: \u003c/p\u003e \n \u003ctable\u003e\n \u003ctr\u003e\n \u003cth\u003eDetected Status\u003c/th\u003e\n \u003ctd\u003e${issueStatus}\u003c/td\u003e\n \u003ctd\u003e:x:\u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\n \u003cth\u003eAllowed Statuses\u003c/th\u003e\n \u003ctd\u003e${allowedStatuses}\u003c/td\u003e\n \u003ctd\u003e:heavy_check_mark:\u003c/td\u003e\n \u003c/tr\u003e\n \u003c/table\u003e\n \u003cp\u003ePlease ensure your jira story is in one of the allowed statuses\u003c/p\u003e\n \n#### Soft-validations via comments\n\n`jira-lint` will add comments to a PR to encourage better PR practices:\n\n**A good PR title**\n\n\u003cfigure\u003e\n \u003cimg src=\"https://user-images.githubusercontent.com/6426069/69525276-c6e62b80-0f8d-11ea-9db4-23d524b5276c.png\" /\u003e\n \u003cfigcaption\u003eWhen the title of the PR matches the summary/title of the issue well.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n---\n\n\u003cfigure\u003e\n \u003cimg src=\"https://user-images.githubusercontent.com/6426069/69480647-6a6cfa00-0e2f-11ea-8750-4294f686dac7.png\" /\u003e\n \u003cfigcaption\u003eWhen the title of the PR is \u003cstrong\u003eslightly different\u003c/strong\u003e compared to the summary/title of the issue\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n---\n\n\u003cfigure\u003e\n \u003cimg src=\"https://user-images.githubusercontent.com/6426069/69526103-7243b000-0f8f-11ea-9deb-acb8cbb6610b.png\" /\u003e\n \u003cfigcaption\u003eWhen the title of the PR is \u003cstrong\u003every different\u003c/strong\u003e compared to the summary/title of the issue\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n---\n\n**A comment discouraging PRs which are too large (based on number of lines of code changed).**\n\n\u003cfigure\u003e\n \u003cimg src=\"https://user-images.githubusercontent.com/6426069/69480043-e06e6280-0e29-11ea-8e24-173355c304dd.png\" /\u003e\n \u003cfigcaption\u003eBatman says no large PRs ๐Ÿฆ‡\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n### Options\n\n| key | description | required | default |\n| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- |\n| `github-token` | Token used to update PR description. `GITHUB_TOKEN` is already available [when you use GitHub actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token#about-the-github_token-secret), so all that is required is to pass it as a param here. | true | null |\n| `jira-token` | Token used to fetch Jira Issue information. Check [below](#jira-token) for more details on how to generate the token. | true | null |\n| `jira-base-url` | The subdomain of JIRA cloud that you use to access it. Ex: \"https://your-domain.atlassian.net\". | true | null |\n| `skip-branches` | A regex to ignore running `jira-lint` on certain branches, like production etc. | false | ' ' |\n| `skip-comments` | A `Boolean` if set to `true` then `jira-lint` will skip adding lint comments for PR title. | false | false |\n| `pr-threshold` | An `Integer` based on which `jira-lint` will add a comment discouraging huge PRs. | false | 800 |\n| `validate_issue_status` | A `Boolean` based on which `jira-lint` will validate the status of the detected jira issue | false | false |\n| `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\"` |\n\n\n### `jira-token`\n\nSince tokens are private, we suggest adding them as [GitHub secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets).\n\nThe Jira token is used to fetch issue information via the Jira REST API. To get the token:-\n1. Generate an [API token via JIRA](https://confluence.atlassian.com/cloud/api-tokens-938839638.html)\n2. Create the encoded token in the format of `base64Encode(\u003cusername\u003e:\u003capi_token\u003e)`.\n For example, if the username is `ci@example.com` and the token is `954c38744be9407ab6fb`, then `ci@example.com:954c38744be9407ab6fb` needs to be base64 encoded to form `Y2lAZXhhbXBsZS5jb206OTU0YzM4NzQ0YmU5NDA3YWI2ZmI=`\n3. The above value (in this example `Y2lAZXhhbXBsZS5jb206OTU0YzM4NzQ0YmU5NDA3YWI2ZmI=`) needs to be added as the `JIRA_TOKEN` secret in your GitHub project.\n\nNote: The user should have the [required permissions (mentioned under GET Issue)](https://developer.atlassian.com/cloud/jira/platform/rest/v3/?utm_source=%2Fcloud%2Fjira%2Fplatform%2Frest%2F\u0026utm_medium=302#api-rest-api-3-issue-issueIdOrKey-get).\n\n### Skipping branches\n\nSince 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](https://github.com/ClearTax/jira-lint/blob/08a47ab7a6e2bc235c9e34da1d14eacf9d810bd1/__tests__/utils.test.ts#L33-L44).\n\n`jira-lint` already skips PRs which are filed by bots (for eg. [dependabot](https://github.com/marketplace/dependabot-preview)). You can add more bots to [this list](https://github.com/ClearTax/jira-lint/blob/08a47ab7a6e2bc235c9e34da1d14eacf9d810bd1/src/constants.ts#L4), or add the branch-format followed by the bot PRs to the `skip-branches` option.\n\n## Contributing\n\nFollow the instructions [here](https://help.github.com/en/articles/creating-a-javascript-action#commit-and-push-your-action-to-github) to know more about GitHub actions.\n\n## FAQ\n\n\u003cdetails\u003e\n \u003csummary\u003eWhy is a Jira key required in the branch names?\u003c/summary\u003e\n\nThe key is required in order to:\n\n- Automate change-logs and release notes โš™๏ธ.\n- Automate alerts to QA/Product teams and other external stake-holders ๐Ÿ”Š.\n- Help us retrospect the sprint progress ๐Ÿ“ˆ.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n \u003csummary\u003eIs there a way to get around this?\u003c/summary\u003e\n Nope ๐Ÿ™…\n\n\u003c/details\u003e\n\n[jira]: https://www.atlassian.com/software/jira\n\n## Contributors\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n \u003ctr\u003e\n \u003ctd align=\"center\"\u003e\u003ca href=\"http://hacktivist.in\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/4851763?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRaj Anand\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ClearTax/jira-lint/commits?author=rajanand02\" title=\"Code\"\u003e๐Ÿ’ป\u003c/a\u003e \u003ca href=\"https://github.com/ClearTax/jira-lint/pulls?q=is%3Apr+reviewed-by%3Arajanand02\" title=\"Reviewed Pull Requests\"\u003e๐Ÿ‘€\u003c/a\u003e \u003ca href=\"#ideas-rajanand02\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e๐Ÿค”\u003c/a\u003e\u003c/td\u003e\n \u003ctd align=\"center\"\u003e\u003ca href=\"https://aditimohanty.com/?utm_source=github\u0026utm_medium=documentation-allcontributors\u0026utm_content=jira-lint\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/6426069?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAditi Mohanty\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ClearTax/jira-lint/commits?author=rheaditi\" title=\"Code\"\u003e๐Ÿ’ป\u003c/a\u003e \u003ca href=\"https://github.com/ClearTax/jira-lint/commits?author=rheaditi\" title=\"Documentation\"\u003e๐Ÿ“–\u003c/a\u003e \u003ca href=\"#infra-rheaditi\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e๐Ÿš‡\u003c/a\u003e\u003c/td\u003e\n \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/dustman9000\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/3944352?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eDustin Row\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ClearTax/jira-lint/pulls?q=is%3Apr+reviewed-by%3Adustman9000\" title=\"Reviewed Pull Requests\"\u003e๐Ÿ‘€\u003c/a\u003e\u003c/td\u003e\n \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/richardlhao\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/60636550?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003erichardlhao\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ClearTax/jira-lint/commits?author=richardlhao\" title=\"Code\"\u003e๐Ÿ’ป\u003c/a\u003e\u003c/td\u003e\n \u003ctd align=\"center\"\u003e\u003ca href=\"https://www.nimeshjm.com/\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/2178497?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eNimesh Manmohanlal\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ClearTax/jira-lint/commits?author=nimeshjm\" title=\"Documentation\"\u003e๐Ÿ“–\u003c/a\u003e\u003c/td\u003e\n \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/lwaddicor\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/10589338?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eLewis Waddicor\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ClearTax/jira-lint/commits?author=lwaddicor\" title=\"Code\"\u003e๐Ÿ’ป\u003c/a\u003e\u003c/td\u003e\n \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-enable --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FClearTax%2Fjira-lint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FClearTax%2Fjira-lint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FClearTax%2Fjira-lint/lists"}