Commit Acceptance Plugin

Added by Ferenc Kiss, last edited by David Chui on Mar 10, 2008  (view change) show comment

Feel free to contribute to the version 2.x design discussions.

Name JIRA Commit Acceptance Plugin
Vendor Atlassian Pty Ltd (Website)
Authors Ferenc Kiss, Bernie Davison, Peter Kolbus
Homepage http://confluence.atlassian.com/display/JIRAEXT/Commit+Acceptance+Plugin
Issue Management http://developer.atlassian.com/jira/browse/CMMT
Categories Administration
Version 1.3
Availability JIRA v3.10.2 to v3.12.3
State Beta
Support Atlassian Supported Plugins
License Freeware / Open Source (BSD)
Price Free
Release Docs http://confluence.atlassian.com/display/JIRAEXT/Commit+Acceptance+Plugin
Java API Docs n/a
Download Source http://svn.atlassian.com/svn/public/contrib/jira/jira-commitacceptance-plugin/tags/version-1.3/
Download JAR jira-commitacceptance-plugin-1.3.jar

Compatibility With JIRA

Plugin Version 3.10.2 3.11 3.12.1 Tested Supported
1.3 David Chui (Jan/29/2008)  
Version 1.3 has been released: support for the Perforce version control system!

We deliver client scripts (written in Perl and in Python) that can deployed as Perforce triggers to better integrate your version control system with JIRA: Perforce change lists can be submitted only if they pass the commit acceptance criteria.

Upgrading from 1.2: if you want to start to use it with Perforce and you already have an existing JIRA instance with the plug in deployed, all you have to do is installing the client scripts as Perforce triggers. The JIRA plugin version 1.2 is perfectly compliant with the new Perforce client scripts shipped in 1.3.

Description/Features

This plug-in lets you define certain basic rules that will determine whether a commit to your version control system will be accepted based on the issues in JIRA. For example, you can define a rule that no commit will be accepted unless it contains a valid issue key. Or you can set a rule that no commit would be accepted if the issue was not in an "open" state.

Currently, this plug-in supports:

  Subversion CVS Perforce ClearCase
Perl Client
Python Client

All these SCM implementations have the concept of pre-commit hooks, which can be used to run arbitrary code at commit-time. The plug-in distribution package contains a set of these hooks that the administrator should install on his/her source code repository and configure for his/her JIRA instance. When a commit is attempted, the hook-script connects to JIRA to evaluate the rules, and then allows or disallows a commit. Projects can have their own specific rules or can use the "global rules".

Inside JIRA, you can configure the rules' behavior on a simple configuration screen (see screenshot at the top of this page).
 

Testimonials

Great plugin, I would almost think this should be part of the standard Jira Package.
Robert Oliver

Thank you for this, a much sought-after plugin I expect!
Owen Carter

This plugin is working very well, thank you very much.
Huw Morgan

Nice plugin; I'm very impressed with the way it works, and also the way the code is architected. It's relatively easy to add new kinds of commit checks.
Peter Kolbus

We love this plugin and our ALM really depends upon it...
John Allen

 

Installation

Server installation

The server side component is just a regular JIRA plug-in. Follow these directions to install:

  1. Copy the plug-in JAR file jira-commitacceptance-plugin-xxx.jar to the JIRA_HOME/atlassian-jira/WEB-INF/lib directory.
  2. Restart JIRA.
  3. To confirm that the plug-in has been successfully installed, go to the administration screen and you should see a new link Commit Acceptance (it requires admin role) in the Project section of the left side menu. Clicking this you should get to the rule configuration screen. Alternatively, you can go to the plug-in list in the administration screen and check whether you can see this plug-in listed there.

Client installation

For each version control system, we provide two equivalent client script, one implemented in Perl and another in Python. You can freely choose between them depending on which runtime environment is available in your system. You can deploy any of these clients to any of the version control systems supported (see the table above), Subversion and CVS.

Download the client scripts.

From version 1.2, we ship advanced versions (developed by Peter Kolbus) of the original client scripts. At the moment these are available only in Python and considered "sandbox quality".
Using these you have a little more control over how arguments are passed from the hooks to the scripts, over how to check against multiple JIRA projects (clients support allof/oneof options).
See more details as comments in the scripts.

By language

Perl client
  • Download here: ActivePerl is currently the most popular way to get Perl for Windows. Perl is already installed on Mac OS X and most Unix OSes.
  • Read the installation documentation here: Win32 Perl Wiki
  • Note that our Perl client depends on the XMLRPC::Lite module. The ActivePerl distribution includes this module, but the original Perl distribution does not. You can use CPAN to install it.
Python client

By version control system

Deploying the client to Subversion

The Subversion client is implemented as a so-called pre-commit hook. To get familiar with the concept of Subversion hooks, please read this and this.

  1. Copy jira-client.pl and pre-commit.bat (or pre-commit.sh on UNIX) to the SUBVERSION_REPOSITORY_HOME/hooks directory.
  2. You can configure the Perl interpreter full path and the jira-client.pl full path in pre-commit.bat. (It's better to use full paths everywhere, because SVN hooks are not aware of the environment.)
  3. You can configure the JIRA access settings (URL, username, password, JIRA project key) and svnlook executable full path in jira-client.pl. Note that our Subversion client must be able to execute the svnlook program.
Deploying the client to CVS

The CVS client is implemented as a verifymsg program. To get familiar with the concept of CVS verifymsg programs, please read this and this.

  1. Copy jira-client.pl and verifymsg to the CVS_HOME/CVSROOT directory.
  2. You can configure the Perl interpreter full path and the jira-client.pl full path in verifymsg.
  3. You can configure the JIRA access settings (URL, username, password, JIRA project key) in jira-client.pl.
Deploying the client to Perforce

The Perforce client is implemented as a so-called change-submit trigger. To get familiar with the concept of Perforce triggers, please read this.

  1. Copy jira-client.pl to some /commitacceptance-clients directory.
  2. As Perforce superuser, add a new trigger by executing the p4 triggers command, and adding a new trigger definition line (for Perl client): 
    Triggers:
        jiracommitacceptance change-submit //depot/... "perl /commitacceptance-clients/jira-client.pl %user% %change%"

    or (for Python client):

    Triggers:
        jiracommitacceptance change-submit //depot/... "python /commitacceptance-clients/jira-client.py %user% %change%"
  3. You can configure the Perl interpreter full path and the jira-client.pl full path directly in this trigger descriptor.
  4. You can configure the JIRA access settings (URL, username, password, JIRA project key) in jira-client.pl.
Deploying the client to ClearCase

This client was contributed by Bernie Davison. He posted the following message to the mailing list:

Users who want to use this script with ClearCase find these details from the Perldoc contained in the script.

"perldoc jira-client.pl" <-- Pointing to the ClearCase version of the script here.

ClearCase is very flexible in how and what triggers can be applied to. The example in the script shows how to apply the trigger to a whole Versioned Object Base (VOB). If a user wanted too this could be reduced further to a file, directory, branch, etc...

If anyone has questions about how to set this trigger up I'm happy to answer them. My email is in the script.

Cheers,
Bernie.

Setting up rules on project basis

  Server Client
Subversion Subversion can have separate hooks for any of its repositories.
If you don't need the commit acceptance functionality, you simply do not install our hook scripts. If you need it, you install the hook scripts to the repositories and specify different $projectKey parameters in them. 		Configure the rules in the serverside.
CVS Unfortunately, CVS supports only one hook in a repository, you cannot configure the hooks on module level. This is simply a limiation in the SCM, that we can't really overcome.
(Workaround: create separate repositories for each of projects (not just the one-module-per-project approach).) 		Configure the rules in the serverside.
Perforce For each trigger, you can specify the path, a file pattern in depot syntax. It is possible to set up any number of triggers, each with its own pattern and parameters. Configure the rules in the serverside.

Usage

You can configure the rules at the Administration -> Commit Acceptance link:

Version History

1.3 (29112007): Support for the Perforce VCS

Atlassian Developer Network JIRA (1 issues)
T Key Summary Status
New Feature CMMT-10 Perforce support for commit acceptance Resolved

1.2 (05102007): Support for Multiple Project Keys in the Client Hook Scripts

Atlassian Developer Network JIRA (3 issues)
T Key Summary Status
New Feature CMMT-12 Support multiple projects per repository (multiple project keys in one hook script) Resolved
Improvement CMMT-16 Only issue keys in the project specified by the projectKey parameter should be accepted Resolved
Bug CMMT-14 The RPC call contained within perl script "jira-client.pl" returns a NULL string as result Resolved

The most important change is that you can specify multiple JIRA project keys in the hook scripts simply as comma-separated values:

my $projectKey = "TST,ARP";

If you specify multiple keys, the commit will be accepted if at least one project listed accepts it.
You can enforce checking against the global settings by passing "projectKey=*" if you don't want to specify any exact JIRA project in the client script.
And you have better control over what issues are accepted in the commit message:

  1. any valid issue
  2. at least one of the issues must be in the mapped project
  3. all issues must be in the mapped project
    See more details in the scripts themselves.

Upgrading from 1.1: 1.1 compliant client scripts can be used with the plugin version 1.2 without any modification.

1.1 (24042007): Support for Project Dependent Rules

Atlassian Developer Network JIRA (7 issues)
T Key Summary Status
Task CMMT-4 Automatized testing Resolved
New Feature CMMT-8 Allow activation by project / repository Resolved
New Feature CMMT-7 Project based configuration of rules Resolved
New Feature CMMT-9 New Client script - ClearCase pre-checkin trigger written in Perl Resolved
Improvement CMMT-1 Configuration page should look like an admin page Resolved
Improvement CMMT-2 Configuration page should be secured Resolved
Bug CMMT-6 Commit error messages are wrongly encoded Resolved

1.0 (28112006): Initial Release with JIRA 3.7

0.2-rc1 (15112006): Second Preview Release

0.1-rc1 (05112006): Initial Preview Release

FAQ

Q. What Subversion clients can I use with this?
A. As all the fun happens on the server-side, you can use any client (including the commandline client, TortoiseSVN, Subclipse, etc).

Q. What CVS clients can I use with this?
A. You can use any client. See previous.

Q. What Perforce clients can I use with this?
A. You can use any client. See previous.

Q. Do I have to use the shell scripts as hooks if my shell is configured to run .pl (or .py) files directly?
A. No. You can have the .pl (or .py) as hook programs, no need for the shellscript, but make sure that you use the full path for perl (or python) in the first line of the .pl (or .py).

Q. I already have hooks in my version control configuration and I have problems when trying add the commit acceptance client scripts to the list.
A. "One thing we noticed during installation is that the hook script provided works fine if you want to fully replace your current hook, but in our case we already have a few check in the pre-commit hook. To get the call to the jira-client.py work work correct (mainly to get the exit condition to work correctly) it has to be the last check in the hook, and the exit 0 that is provided as the last line of the default SVN provided pre-commit hook has to be commented out." (From Lehky, Miro.)

Troubleshooting

Q. I get "javax.servlet.ServletException: Remote API not activated for this JIRA installation." when trying to commit a change.
A. You have to enable remote API calls at the 'Administration' section. Go to 'General Configuration' and turn it on using 'Edit Configuration'.

Q. When running the CVS server on Windows, I get "Unknown escape character '\m' ignored." message.
A. Please use double backslashes in the path names in your verifymsg:

DEFAULT	python.exe C:\\myscripts\\jira-client.py ${USER}

Q. My hook cannot find the files even if I use names that are in the PATH.
A. SVN have the hooks run in an empty environment, so please use full absolute paths everywhere.

Q. Something fails when the hook is invoked by SVN, but I can't see any error message.
A. Unfortunately, SVN swallows both the output written to stdout, so you should use stderr.

Q. I think my hook is not called by the SCM system. How can I double check whether my hook is invoked at all?
A. You can use a dummy test hook program like this, but never rely on writing to stdout. If your hook was invoked you should find dummy.txt after, in the same folder.

full/path/to/my/bin/echo hoorayiamhere >> dummy.txt

Q. I think there's something wrong the .pl (or .py) I'm using. How can I check this?
A. You can actually run the scripts manually, not through the hooks. They will necessarily fail (as they expect receiving some parameters from SCM system), but at least you can see if they are successfully started and check basic syntax- or similar errors.

Q. It seems my client scripts can't connect to the JIRA instance because of request context path problems...
A. "I had:

jiraBaseURL = 'http://10.1.0.41:8280/jira' and
s = xmlrpclib.ServerProxy(urlparse.urljoin(jiraBaseURL, '/rpc/xmlrpc'))

and this does not work. But

jiraBaseURL = 'http://10.1.0.41:8280' and
s = xmlrpclib.ServerProxy(urlparse.urljoin(jiraBaseURL, 'jira/rpc/xmlrpc'))

works." (From marco kundert.)

Labels

 

Comments (69)

 

  1. Jan 03, 2007

    Lehky, Miro says:

    Ferenc This plug in is working very well.&nbsp; One thing we noticed during&nbsp...

    Ferenc

    This plug in is working very well.  One thing we noticed during installation is that the hock script provided works fine if you want to fully replace your current hook, but in our case we already have a few check in the pre-commit hook.  To get the call to the jira-client.py work work correct (mainly to get the exit condition to work correctly) it has to be the last check in the hook, and the exit 0 that is provided as the last line of the default SVN provided pre-commit hook has to be commented out.

    The only enhancement that would greatly improve the utility of this plug-in would be to allow configuration of a different set of checks per JIRA project.

    Thanks

    Miro 

    1. Jan 04, 2007

      Ferenc Kiss says:

      Thank you very much for your comments, Miro. I've added your insights about the...

      Thank you very much for your comments, Miro.

      I've added your insights about the "multiple hooks" problem to the FAQ.

      About the feature request: this request is already existing in our JIRA here: http://developer.atlassian.com/jira/browse/CMMT-8 Feel free to incease its popularity.

      1. Jan 05, 2007

        Lehky, Miro says:

        Ferenc We did notice no more thing today.&nbsp; In addition to users making comm...

        Ferenc

        We did notice no more thing today.  In addition to users making commits, our build system also makes commits in order to create a tag when each QA and Release build is done (build system is QuickBuild).  The commit by the build system does not have an issue number (but does have comment text).  This was precluding the use of the checks against the JIRA Issue key, which is the main check we want to use for user commits.

        The only work around i was able to come up with was to create a user account under which to run the build system, then add a check jira-client.py which checks for this committer and immedialy does an exit 0 if the committer is the build system.

        I wonder if thier are any other wasy to approach this problem.

        1. Jan 05, 2007

          Ferenc Kiss says:

          Hmm, I think your solution is creative and at the moment I can't think of anythi...

          Hmm, I think your solution is creative and at the moment I can't think of anything better.

          A less tricky solution would be if the plugin supported rules not only per-project, but per-user basis, but that'd be a definite overkill for now.

    2. Jan 14, 2007

      Rob Baily says:

      Just FYI if you are using SVN on some sort of UNIX flavor you can add these line...

      Just FYI if you are using SVN on some sort of UNIX flavor you can add these lines into an existing shell script pre-commit at whatever spot you want to perform the check. If the check fails it will stop here otherwise it can move on if you want other checks after it.

      HOOKDIR=`dirname $0`
$HOOKDIR/jira-client.pl "$REPOS" "$TXN" || exit 1

      1. Jan 14, 2007

        Ferenc Kiss says:

        Thank you for the hint, Rob. Plz keep'em coming' in the future :)

        Thank you for the hint, Rob. Plz keep'em coming' in the future

  2. Jan 29, 2007

    Huw Morgan says:

    Ferenc First of all ths plugin is working very well, thank you very much. I ha...

    Ferenc

    First of all ths plugin is working very well, thank you very much.

    I have a small suggestion, to make the one of the errors messages a little clearer.

    If I commited a change to subversion repository with an issue number which did not exist in Jira but was of the correct form, the error message returned was:
    Unable to connect to the JIRA server at "http://myserver:8080".

    A clearer message would be something like
    "Issue [XYZ-123] does not exist"

    Of course if the client really can not connect to the Jira server then a message like:
    Unable to connect to the JIRA server at "http://myserver:8080"
    is entirely appropriate.

    Thank you once again for a great plugin.
    Huw Morgan

    1. Jan 30, 2007

      Ferenc Kiss says:

      Nice to hear that you've found it useful, Huw. Thanks for your report, too, th...

      Nice to hear that you've found it useful, Huw.

      Thanks for your report, too, that message is definitely misleading. Could you post this as a cosmetic issue to our JIRA? We'd address it with the next release.

  3. Mar 15, 2007

    Owen Carter says:

    Ferenc; Thankyou for this, A much soughtafter plugin I expect\! I'm looking for ...

    Ferenc;
    Thankyou for this, A much sought-after plugin I expect!

    I'm looking for clarification about the scope to which this applies, I thought it would make a good FAQ note too.

    Per-Project: I believe (from a look at the code) that this plugin only applies to the whole Jira configuration, and cannot be implemented in a 'per project' basis at the Jira Level.

    Per-repository: I cannot see any way of implementing hooks in SVN at anything other than a 'Per repository' manner, I guess this is a Subversion limitation really.

    I've got the ago old problem of an existing install of both Jira and SVN, where we only have one SVN repositroy that is used by multiple projects.  And different project teams would like different policies (shrugs shoulders .

    I assume that at the moment I'm borked? and I'd either need to break up the repositories, or add logic to the hooks to exclude/include relevent paths depending on our needs (If I do I'll put the results on your Jira tracker).

    Ideally I'd like to be able to specify this 'Per Project' in Jira, and specify there the repository paths to be included. I have some deeper thoughts on this, shall I put them in CMMT-8?

    1. Mar 19, 2007

      Ferenc Kiss says:

      Hi Owen\! Thanks for your feedback. Yes, I'd like to ask you to put your suggest...

      Hi Owen!

      Thanks for your feedback.

      Yes, I'd like to ask you to put your suggestions to the related JIRA task so that we have everything in a single place when we address this issue.

  4. Apr 05, 2007

    John Allen says:

    Hi Ferenc, We love this functionality and look forward to future enhancements to...

    Hi Ferenc,

    We love this functionality and look forward to future enhancements to it however I thought I might point out that the embedded user authentication required by the scripts is not really going to fly in a big environment. Embedded passwords are nasty at the best of times and when JIRA finally gets it's act together and supports real LDAP it will be even worse. I understand that for project's that have permissions schemes that prevent anonymous access then they will have no choice but to provide the authentication details in the clients (and thus the svn hooks) but a lot of projects do allow anonymous read access and thus don't need these authentication details.

    1. Apr 05, 2007

      Ferenc Kiss says:

      Well, good point. Thank you very much for comments, John. Do you have a suggest...

      Well, good point. Thank you very much for comments, John.

      Do you have a suggestion how to handle the authentication problem that is a generic solution for any of the situation you mentioned? Is it all you need to check if the project can be accessed anonymously when a blank username and password was passed from the client?

  5. May 16, 2007

    Lehky, Miro says:

    In the new version is thier any way to configure a single repository to check mu...

    In the new version is thier any way to configure a single repository to check multipe JIRA projects?

    Thanks

    Miro

    1. May 26, 2007

      Ferenc Kiss says:

      No, this is not supported yet, but sounds like an interesting feature request (a...

      No, this is not supported yet, but sounds like an interesting feature request (and seems relatively easy to implement). Could you post it as feature request to the project JIRA? What would be the relation between the multiple project criteria? Should ALL of them accept the commit or ANY of them? In other words, is it AND or OR between them? To me, AND seems more reasonable.

      1. Jul 15, 2007

        Kevin Menard says:

        I just wanted to weigh in on this one, and since I can't seem to do much of anyt...

        I just wanted to weigh in on this one, and since I can't seem to do much of anything with the project's JIRA instance, I figure here's the best place I can.

        I'd say it should be an "OR" relationship. The crux of the matter is that it's fairly customary to have some sort of SVN root from which other projects are created. It can make configuration easier for a lot of tools. For example, ViewVC rewards users for having a common root, as does Subversion itself (see: SVNParentPath). In this case, we could have something like the following:

        http://localhost/svn/root/www
        http://localhost/svn/root/some_swing_app

        On the filesystem, these may map to the repository at:

        /svnroot/root/

        "www" and "some_swing_app" have nothing to do with each other. Without a doubt, they'll each have their own projects in JIRA. However, since the repository is the common "root", the pre-commit hook needs to be able to handle both.

        1. Jul 17, 2007

          Ferenc Kiss says:

          Thank you, Kevin. I've added your comment to

          Thank you, Kevin. I've added your comment to http://developer.atlassian.com/jira/browse/CMMT-12

  6. Jun 22, 2007

    Huw Morgan says:

    Ferenc in version 1.1 I like the addition of being able to associate the commit...

    Ferenc

    in version 1.1 I like the addition of being able to associate the commit action with a given project. Might I suggest that the jira-client.py (and other related clients) might be easier to work with if you could specify the jira project key as a command line argument rather than hard coding it as variable in the jira-client.py script. This would make it much easier to use in a multi-repository multi-jra-project environment.

    Thanks for improving the error messaage as per one of my previous comments.

    Regards
    Huw Morgan

    1. Jun 22, 2007

      Ferenc Kiss says:

      Thank you very much for the feedback, Huw. However, our main focus is primarily ...

      Thank you very much for the feedback, Huw. However, our main focus is primarily on improving the serverside logic and provide the hook scripts as "templates" that you custom-tailor to your environment, your request makes sense.

      Could you post it to our JIRA as feature request?

      Thanks.

    2. Nov 07, 2007

      James Lacey says:

      This was an issue for our company too. Here is something I hacked together for t...

      This was an issue for our company too. Here is something I hacked together for the client script (we are using Perl):

      my $sedPath = "C:\\usr\\local\\wbin\\sed.exe";
open IN, '-|', "$svnlookPath log $ARGV[0] --transaction $ARGV[1] | \
  $sedPath -n s/\\W*\\([a-zA-Z]*\\)\\-[0-9]*.*/\\1/p" \
  or die "Unable to get project key with svnlook.\n";
my $projectKey = <IN>;
close IN;
chomp($projectKey);

      Usually, we do our log messages like this:

      PROJ-100 I fixed a bug.

      YMMV depending upon how you format your log messages. However, in that case, you just need to tweak the regular expression for sed.

  7. Jun 25, 2007

    Alan Mosely says:

    Hi, We are developing a JIRA RPC plugin that enforces our specific continuous in...

    Hi,

    We are developing a JIRA RPC plugin that enforces our specific continuous integration commit acceptance criteria (checks if the main build is broken before allowing a commit etc), and are at the moment using your plugin to regulate checkins.

    Instead of replicating or integrating your code, we would like to have our plugin call yours locally before running through our specific CI checks. What would be the best way to do this?

    Thanks for your help,

    1. Jun 27, 2007

      Ferenc Kiss says:

      Hello Alan, There is a couple of approach you can take here: # if you want to c...

      Hello Alan,

      There is a couple of approach you can take here:

      1. if you want to call our plugin from yours, you can call the main entry point of the Evaluator class and then check the the return value. This seems like a very easy to implement thing, but probably not the most elegant one.
      2. alternatively, you could implement your specific rules as custom Predicate concrete classes. Custom predicates are not really supported at the moment, but please feel free to post a feature request to our JIRA or contact us if you would like us to help you out with this before the next release. (If you need a config GUI in front of your custom predicates, that can add a lot of extra workload and if you want to make it really generic, well, that is a lot harder...)

  8. Jun 27, 2007

    Alan Mosely says:

    Ferenc, Thanks for your advice, will investigate the approaches you advise. Am i...

    Ferenc,

    Thanks for your advice, will investigate the approaches you advise.

    Am i right in reading between the lines that custom predicates will be supported in the next release?