Git::Hooks::CheckJira - Git::Hooks plugin which requires citation of JIRA issues in commit messages.
version 0.051
This Git::Hooks plugin hooks itself to the hooks below 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.
commit-msg
This hook is invoked during the commit, to check if the commit message cites valid JIRA issues.
update
This hook is invoked multiple times in the remote repository during git push, once per branch being updated, to check if the commit message cites valid JIRA issues.
git push
pre-receive
This hook is invoked once in the remote repository during git push, to check if the commit message cites valid JIRA issues.
ref-update
This hook is invoked when a push request is received by Gerrit Code Review, to check if the commit message cites valid JIRA issues.
patchset-created
This hook is invoked when a push request is received by Gerrit Code Review for a virtual branch (refs/for/*), to check if the commit message cites valid JIRA issues.
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 hyphen from a sequence of digits. E.g., CDS-123, RT-1, and GIT-97.
CDS-123
RT-1
GIT-97
To enable it you should add it to the githooks.plugin configuration option:
git config --add githooks.plugin CheckJira
CheckJira - Git::Hooks plugin which requires citation of JIRA issues in commit messages.
The plugin is configured by the following git options.
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)").
^
This variable is deprecated. Please, use the githooks.userenv variable, which is defined in the Git::Hooks module. Please, see its documentation to understand it.
githooks.userenv
This variable is deprecated. Please, use the githooks.admin variable, which is defined in the Git::Hooks module. Please, see its documentation to understand it.
githooks.admin
This option specifies the JIRA server HTTP URL, used to construct the JIRA::REST object which is used to interact with your JIRA server. Please, see the JIRA::REST documentation to know about them.
JIRA::REST
This option specifies the JIRA server username, used to construct the JIRA::REST object.
This option specifies the JIRA server password, used to construct the JIRA::REST object.
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 hyphen, followed by a sequence of digits. If you customized your JIRA 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. You do this by specifying a regular expression with a capture group (a pair of parenthesis) in it. The commit message is matched against the regular expression and the JIRA tickets are looked for only within the part that matched the capture group.
Here are some examples:
\[([^]]+)\]
Looks for JIRA keys inside the first pair of brackets found in the message.
(?s)^\[([^]]+)\]
Looks for JIRA keys inside a pair of brackets that must be at the beginning of the message's title.
(?im)^Bug:(.*)
Looks for JIRA keys in a line beginning with Bug:. This is a common convention around some high caliber projects, such as OpenStack and Wikimedia.
Bug:
This is a multi-valued option. You may specify it more than once. All regexes are tried and JIRA keys are looked for in all of them. This allows you to more easily accomodate more than one way of specifying JIRA keys if you wish.
By default, the committer 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 allow more than one project by specifying this option multiple times, once per project key.
If you set this option, then any cited JIRA issue that doesn't belong to one of the specified projects causes an error.
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 committer can reference any valid JIRA issue. Setting this value 1 requires that the user doing the push/commit (as specified by the userenv configuration variable) be the current issue's assignee.
userenv
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:
GIT
The Git repository object used to grok information about the commit.
COMMITID
The SHA-1 id of the Git commit. It is undef in the commit-msg hook, because there is no commit yet.
JIRA
The JIRA::REST object used to talk to the JIRA server.
Note that up to version 0.047 of Git::Hooks::CheckJira this used to be a JIRA::Client object, which uses JIRA's SOAP API which was deprecated on JIRA 6.0 and won't be available anymore on JIRA 7.0.
If you have code relying on the JIRA::Client module you're advised to rewrite it using the JIRA::REST module. As a stopgap measure you can disregard the JIRA::REST object and create your own JIRA::Client object.
ISSUES...
The remaining arguments are RemoteIssue objects representing the issues being cited by the commit's message.
The subroutine should return a boolean value indicating success. Any errors should be produced by invoking the Git::More::error method.
If the subroutine returns undef it's considered to have succeeded.
If it raises an exception (e.g., by invoking die) it's considered to have failed and a proper message is produced to the user.
This module exports two routines that can be used directly without using all of Git::Hooks infrastructure.
This is the routine used to implement the update and the pre-receive hooks. It needs a Git::More object.
Git::More
This is the routine used to implement the commit-msg hook. It needs a Git::More object and the name of a file containing the commit message.
This is the routine used to implement the patchset-created Gerrit hook. It needs a Git::More object and the hash containing the arguments passed to the hook by Gerrit.
JIRA::Client
Gustavo L. de M. Chaves <gnustavo@cpan.org>
This software is copyright (c) 2014 by CPqD <www.cpqd.com.br>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
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.