Skip to content

A lightweight solution to integrate GitHub with JIRA for project management.

License

Notifications You must be signed in to change notification settings

cakeinpanic/jira-description-action

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

jira-description-action

A lightweight solution to integrate GitHub with JIRA for project management. 🔎

illustration

Installation

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

Note This action fetches PR description and does not take it form context. So if you are chaining a few actions which work with PR description, put this one as the last one

name: jira-description-action
on:
  pull_request:
    types: [opened, edited]
jobs:
  add-jira-description:
    runs-on: ubuntu-latest
    steps:
      - uses: cakeinpanic/jira-description-action@master
        name: jira-description-action
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          jira-token: ${{ secrets.JIRA_TOKEN }}
          jira-base-url: https://your-domain.atlassian.net
          skip-branches: '^(production-release|main|master|release\/v\d+)$' #optional 
          custom-issue-number-regexp: '^\d+' #optional
          jira-project-key: 'PRJ' #optional    

`

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. The GITHUB_TOKEN needs to have read & write permissions over the repository. You can either set permissions in the workflow file, or in the repository configuration. (see Control permissions for GITHUB_TOKEN) 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-description-action on certain branches, like production etc. false ' '
use Enum: branch | pr-title | both, to search for issue number in branch name or in PR title false pr-title
jira-project-key Key of project in jira. First part of issue key false none
custom-issue-number-regexp Custom regexp to extract issue number from branch name. If not specified, default regexp would be used. false none
fail-when-jira-issue-not-found Should action fail if jira issue is not found in jira false false

Outputs

key description
jira-issue-key The JIRA issue key. If key is not found the value is an empty string
jira-issue-found Indication whether a jira issue was found or not
jira-issue-source Indication how the jira issue was found, by - branch | pr-title | null

Tokens are private, so it's suggested adding them as GitHub secrets.

Features

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. Add value <jira username>:<jira api token> to the JIRA_TOKEN secret in your GitHub project. For example, if the username is ci@example.com and the token is 954c38744be9407ab6fb, then ci@example.com:954c38744be9407ab6fb needs to be added as a secret

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

Skipping branches

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 in thi repo

jira-description-action already skips PRs which are filed by dependabot

Searching in branch name/PR title

By default issue key is searched in PR title(which can easily be changed). use option can be set to branch if you want to get issue key from branch name. Or to both to look first in pr-title, then in branch name

Using custom regex

If custom-issue-number-regexp is not provided, full key of issue is searched using regexp /([a-zA-Z0-9]{1,10}-\d+)/g;. For example

bugfix/prj-15-click -> PRJ-15
prj-15-bugfix-17 -> PRJ-17
15-bugfix -> nothing found

Custom regexp would work like that(check for more in tests):

custom-issue-number-regexp: 'MYPROJ-\d+' 
bugfix/MYPROJ-15-click -> MYPROJ-15
prj-15-myproj-17 -> MYPROJ-15 // it is insensitive by design
15-bugfix -> null

If you don't use full keys in branch names, you can specify optional parameters to compute issue keys. It would be appended to found key as ${jira-project-key}-{regexp-match}:

jira-project-key: 'MYPROJ'
custom-issue-number-regexp: '\d+' 
bugfix/prj-15-click -> MYPROJ-15
prj-15-bugfix-17 -> MYPROJ-15
15-bugfix -> MYPROJ-15

Groups in regexp can also be used(last group in a match would be taken):

jira-project-key: 'MYPROJ'
custom-issue-number-regexp: '-(\d+)' 
bugfix/prj15-239-click -> MYPROJ-239
15-bugfix -> null

Custom label placement

By default label would be prepended to the PR body. If you want it to be placed elsewhere in the description, you can add markers in the pull request template for the repository.

Label would be inserted between these marker lines:

<!--jira-description-action-hidden-marker-start-->

<!--jira-description-action-hidden-marker-end-->

About

A lightweight solution to integrate GitHub with JIRA for project management.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published