check-jira.pl [--verbose] [--hook=commit-msg] COMMIT_MSG_FILE check-jira.pl [--verbose] [--hook=update] REF OLD_COMMIT NEW_COMMIT check-jira.pl [--verbose] [--hook=pre-receive]
This script can act as one of three different Git hooks to guarantee that every commit message cites at least one valid JIRA issue key in its log message, so that you can be certain that every change has a proper change request (a.k.a. ticket) open.
It requires that any Git commits affecting all or some branches must make reference to valid JIRA issues in the commit log message. JIRA issues are cited by their keys which, by default, consist of a sequence of uppercase letters separated by an hyfen from a sequence of digits. E.g., CDS-123, RT-1, and GIT-97.
CDS-123
RT-1
GIT-97
To install it you must copy (or link) it to one of the three hook files under .git/hooks in your Git repository: commit-msg, pre-receive, and update. In this way, Git will call it with proper name and arguments. For each hook it acts as follows:
.git/hooks
commit-msg
pre-receive
update
This hook is invoked locally during git commit before it's completed. The script reads the proposed commit message and checks if it cites valid JIRA issue keys, aborting the commit otherwise.
git commit
This hook is invoked multiple times in the remote repository during git push, once per branch being updated. The script checks every commit being updated for the branch.
git push
This hook is invoked once in the remote repository during git push. The script checks every commit being updated for every branch.
It is configured by the following git options, which can be set via the git config command. Note that you may have options set in any of the system, global, or local scopes. The script will use the most restricted one.
git config
By default, the message of every commit is checked. If you want to have them checked only for some refs (usually some branch under refs/heads/), you may specify them with one or more instances of this option.
The refs can be specified as a complete ref name (e.g. "refs/heads/master") or by a regular expression starting with a caret (^), which is kept as part of the regexp (e.g. "^refs/heads/(master|fix)").
^
When this hook is installed, by default no user can commit without being subject to the hooks configuration regarding the need to cite JIRAs. It may be usefull, however, to give full access to a group of admins who shouldn't be subject to the JIRA requirements. You may use one or more such options to give admin access to a group of people. The value of each option is interpreted in one of these ways:
A username specifying a single user. The username specification must match "/^\w+$/i" and will be compared to the authenticated user's name case sensitively.
username
A regex which will be matched against the authenticated user's name case-insensitively. The caret is part of the regex, meaning that it's anchored at the start of the username.
regex
These options are required and are used to construct the JIRA::Client object which is used to interact with your JIRA server. Please, see the JIRA::Client documentation to know about them.
JIRA::Client
By default, JIRA keys are matched with the regex /\b[A-Z][A-Z]+-\d+\b/, meaning, a sequence of two or more capital letters, followed by an hyfen, followed by a sequence of digits. If you customized your JIRA project keys (https://confluence.atlassian.com/display/JIRA/Configuring+Project+Keys), you may need to customize how this hook is going to match them. Set this option to a suitable regex to match a complete JIRA issue key.
/\b[A-Z][A-Z]+-\d+\b/
By default, JIRA keys are looked for in all of the commit message. However, this can lead to some false positives, since the default issue pattern can match other things besides JIRA issue keys. You may use this option to restrict the places inside the commit message where the keys are going to be looked for.
For example, set it to "\[([^]]+)\]" to require that JIRA keys be cited inside the first pair of brackets found in the message.
\[([^]]+)\]
By default, the commiter can reference any JIRA issue in the commit log. You can restrict the allowed keys to a set of JIRA projects by specifying a JIRA project key to this option. You can enable more than one project by specifying more than one value to this option.
By default, the log must reference at least one JIRA issue. You can make the reference optional by setting this option to 0.
By default, every issue referenced must be unresolved, i.e., it must not have a resolution. You can relax this requirement by setting this option to 0.
By default, the commiter can reference any valid JIRA issue. Setting this value to the name of an environment variable, the script will check if its value is equal to the referenced JIRA issue's assignee.
If the above checks aren't enough you can use this option to define a custom code to check your commits. The code may be specified directly as the option's value or you may specify it indirectly via the filename of a script. If the option's value starts with "file:", the remaining is treated as the script filename, which is executed by a do command. Otherwise, the option's value is executed directly by an eval. Either way, the code must end with the definition of a routine, which will be called once for each commit with the following arguments:
The subroutine must simply return with no value to indicate success and must die to indicate failure.
Please, read the JIRA::Client and Git::More modules documentation to understand how to use these objects.
Git::More
This script is heavily inspired (and sometimes derived) from Joyjit Nath's git-jira-hook (https://github.com/joyjit/git-jira-hook).
To install Git::Hooks, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Git::Hooks
CPAN shell
perl -MCPAN -e shell install Git::Hooks
For more information on module installation, please visit the detailed CPAN module installation guide.