View on
MetaCPAN
Gustavo Leite de Mendonça Chaves > Git-Hooks > Git::Hooks::CheckJira

Download:
Git-Hooks-2.1.6.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: v2.1.6   Source  

NAME ^

Git::Hooks::CheckJira - Git::Hooks plugin which requires citation of JIRA issues in commit messages

VERSION ^

version 2.1.6

DESCRIPTION ^

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.

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.

To enable it you should add it to the githooks.plugin configuration option:

    git config --add githooks.plugin CheckJira

NAME ^

CheckJira - Git::Hooks plugin to implement JIRA checks

CONFIGURATION ^

The plugin is configured by the following git options.

githooks.checkjira.ref REFSPEC

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)").

githooks.checkjira.noref REFSPEC

By default, the message of every commit is checked. If you want to exclude 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 in the same way as to the ref option above.

Note that the ref option has precedence over the noref option, i.e., if a reference matches both options it will be checked.

githooks.checkjira.jiraurl URL

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.

githooks.checkjira.jirauser USERNAME

This option specifies the JIRA server username, used to construct the JIRA::REST object.

githooks.checkjira.jirapass PASSWORD

This option specifies the JIRA server password, used to construct the JIRA::REST object.

githooks.checkjira.matchkey REGEXP

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.

githooks.checkjira.matchlog REGEXP

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:

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 accommodate more than one way of specifying JIRA keys if you wish.

githooks.checkjira.jql JQL

By default, any cited issue must exist on the server and be unresolved. You can specify other restrictions (and even allow for resolved issues) by specifying a JQL expression which must match all cited issues. For example, you may want to:

githooks.checkjira.ref-jql REF JQL

You may impose restrictions on specific branches (or, more broadly, any reference) by mentioning them before the JQL expression. REF 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)"). For instance:

  [githooks "checkjira"]
    jql = refs/heads/master fixVersion = future
    jql = ^refs/heads/release/ fixVersion IN releasedVersions()

githooks.checkjira.require [01]

By default, the log must reference at least one JIRA issue. You can make the reference optional by setting this option to 0.

githooks.checkjira.unresolved [01]

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.

githooks.checkjira.fixversion BRANCH FIXVERSION

This multi-valued option allows you to specify that commits affecting BRANCH must cite only issues that have their Fix For Version field matching FIXVERSION. This may be useful if you have release branches associated with particular JIRA versions.

BRANCH 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)").

FIXVERSION can be specified as a complete JIRA version name (e.g. "1.2.3") or by a regular expression starting with a caret (^), which is kept as part of the regexp (e.g. "^1\.2").

As a special feature, if BRANCH is a regular expression containing capture groups, then every occurrence of the substring $+ in FIXVERSION, if any, is replaced by the text matched by the last capture group in BRANCH. (Hint: Perl's $+ variable is defined as "The text matched by the last bracket of the last successful search pattern.") If FIXVERSION is also a regular expression, the $+ are replaced by the text properly escaped so that it matches literally.

Commits that do not affect any BRANCH are accepted by default.

So, suppose you have this configuration:

  [githooks "checkjira"]
    fixversion = refs/heads/master          future
    fixversion = ^refs/heads/(\d+\.\d+)\.   ^$+

Then, commits affecting the master branch must cite issues assigned to the future version. Also, commits affecting any branch which name begins with a version number (e.g. 1.0.3) be assigned to the corresponding JIRA version (e.g. 1.0).

githooks.checkjira.by-assignee [01]

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.

githooks.checkjira.check-code CODESPEC

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 should return a boolean value indicating success. Any errors should be produced by invoking the Git::Repository::Plugin::GitHooks::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.

githooks.checkjira.comment VISIBILITY

If this option is set and the post-receive hook is enabled, for every pushed commit, every cited JIRA issue receives a comment showing the result of the git show --stat COMMIT command. This is meant to notify the issue assignee of commits referring to the issue.

Note that the user with which Git::Hooks authenticates to JIRA must have permission to add comments to the issues or an error will be logged. However, since this happens after the push, the result of the operation isn't affected.

You must specify the VISIBILITY of the comments in one of these ways.

githooks.checkjira.skip-merges [01]

By default, all commits are checked. You can exempt merge commits from being checked by setting this option to 1.

githooks.checkjira.project KEY

This option is DEPRECATED. Please, use a JQL expression such the following to restrict by project key:

  project IN (ABC, GIT)

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.

githooks.checkjira.status STATUSNAME

This option is DEPRECATED. Please, use a JQL expression such the following to restrict by status:

  status IN (Open, "In Progress")

By default, it doesn't matter in which status the JIRA issues are. By setting this multi-valued option you can restrict the valid statuses for the issues.

githooks.checkjira.issuetype ISSUETYPENAME

This option is DEPRECATED. Please, use a JQL expression such the following to restrict by issue type:

  issuetype IN (Bug, Story)

By default, it doesn't matter what type of JIRA issues are cited. By setting this multi-valued option you can restrict the valid issue types.

SEE ALSO ^

REFERENCES ^

AUTHOR ^

Gustavo L. de M. Chaves <gnustavo@cpan.org>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2017 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.

syntax highlighting: