Welcome to Change Integration for Jira (Jira2Svn), integration Subversion, Git and Mercurial with the Jira change management system.
This guide covers the installation and configuration of the Jira, server and hook components. For information on the client component, please refer to the Java Client User Guide.
If you're running Windows Vista, there are two steps which you need to carry out before Change Integration for Jira functions correctly.
You will need to choose a machine to run the Jira2SVN Server, and choose a port number for Jira2SVN to use (eg, we recommend 54322). Note that the client machines will require access to this port on the Server (and this may require firewall configuration). As per the IANA recommendations, we recommend that you use one of the Dynamic and/or Private Ports from 49152 through 65535.
Jira2SVN is designed with maximum flexibility in mind to cater for various network infrastructure requirements. Therefore, the physical location of all the components is flexible. In particular, the location of the Jira2SVN Server is flexible to help mange network traffic and data latencies. It may be installed on your Subversion server machine, your JIRA server machine or on its own machine as shown below.
In some environments, it makes sense to locate the JIRA2SVN Server on the JIRA machine itself.
In other organisations, it might make sense to locate the Jira2SVN Server on the Subversion, Git or Mercurial server.
Jira2SVN can support multiple Subversion, Git or Mercurial servers either using separate or shared JIRA datbases. So, for example, to use one common JIRA database with 2 Subversion repositories, set up one Jira2SVN Server for each Subversion repository, each pointing to the shared JIRA Server. On each User machine, run 2 Jira2SVN clients, each with its own Jira2SVN.cfg file (pointing to it's respective Jira2SVN Server). This way, whenever a commit is made to either repository, the Jira record is requested from the User.
The following section describes at a high level the various communications
Evaluation licenses can be requested from the clearvision website: http://www.clearvision-cm.com
A link to the license request form for a product can be found on the product's download page. To request a license we need some information about the machine that you will be running the server on. To get this information, you can run the get_license_info program on the machine you want to use as the server (the get_license_info program can be found within the tools directory of the installation directory). This will retrieve and present system information from the machine.
Once the license request form has been completed and submitted, an email will be sent to the registered email address containing the license infomation. This information will need to be inserted into the server config file.
Note that this license will only work on a particular server machine, on a particular port, and will allow a maximum number of users. The license is time-limited so it is recommended that Evaluation licenses are not requested until needed.
Once a license has been purchased, you will receive an email containing a link to the online full license generator. A similar form will need to be filled in as for an evaluation license. Once the form has been completed and confirmed a full license will be emailed. Any evaluation license details in the config file will need to be replaced by the full license.
Licenses are tied to the hardware as well as the IP address of the machine used for the server. It is therefore necessary to ensure these details will not change as this will leave the license invalid.
License Request for Clearvision Jira2SVN:
Evaluation: yes/no
IP Address: 192.168.64.1
Port: 54322
MAC Address: 00-50-56-C0-00-05
Users: 50
Company: You Company name here
Email Address: yourco@yourco.com
Expiry Date: 2008-03-31
Product: JIRA2SVN
The get_license_info executable is run from a command prompt, eg on Windows:
<jira-renderer system="true" key="jira2svn-hidden-renderer" name="Hidden Text Renderer"
class="com.clearvision.jira2svn.HiddenTextRenderer">
<description>A renderer that will not display the content of a field. Used for hiding contents of the JIRA2SVN custom field.</description>
<resource type="velocity" name="edit" location="templates/plugins/renderers/text/text-renderer-edit.vm"/>
</jira-renderer>
Enable the XML-RPC and SOAP remote JIRA APIs as described in the Jira documentation, in summary:
Create a filter to get the list of issues that would be relevant to a typical Jira2SVN user. For example, you could create a filter to return all outstanding bugs or features for the 'Current User'. Make sure that this filter is usable by everyone who will use Jira2SVN (for example by 'sharing' the filter with everyone).
Write down the id of the filter (a number like '10001'). You can find it at the end of the URL after creating a new filter, or when you view a filter.
Jira2SVN captures information about the change from Subversion/Git/Mercurial and stores it in a custom field in JIRA. Note: Unlike the Atlassian plugin, this means that the change information is permanently available for reporting and audit purposes.
To add the field:
Note the numerical part of the field you've just added, something like 10010. You can find the id within the URL in your browser once you have created the field, e.g. fieldId=customfield_10010 or at the end of the URL when you edit the field.
You can associate the jira2svn field with the HiddenTextRenderer. This is an optional step that will make tickets with a large number of file associations more readable by hiding the raw data, which is normally displayed at the top of a ticket:
Jira2SVN has 4 separate parts: a client, a server, a JIRA Plugin and a set of files which must be installed in your Subversion, Git and/or Mercurial repository's hooks directory. There is also a tool to get license information from your Jira2SVN Server in the tools directory.
Start by unpacking the zip file into the C:\Program Files location on all of the machines that you will be installing on (any location can be used, however all the configuration files and instructions below use C:\Program Files as an example). The following directory structure will be created:
NOTE Please take care when editing any configuration files. We recommend the use of text editors such as Vim. Wordpad should also work, but please do not use Notepad or MS Word as it may insert formatting information into your config file, which can cause the config reader to fail.
On your Jira2SVN Server machine:
[JIRA] filter_id=10010 jira2svn_custom_field_id=10000 jira_server=http://issues.mycompany.com:8080 [License] company_name=Your Company Plc licence_email=admin@yourcompany.com expiry_date=2008-12-31 users=999 license_key=PLEASE_ADD_YOUR_LICENCE_key_HERE license_certificate=PLEASE_ADD_YOUR_LICENCE_certificate_HERE [Server] server_ip=192.168.1.2 server_port=54322
cd c:\Program Files\Clearvision\jira2svn\server jira2svn_server.exe
On Windows, we recommend that you add the Jira2SVN Server as a 'Scheduled Task', 'When my computer starts'.
An alternative would be to add an item in the autoexec.nt file so that the server is started on boot and is available for all users. Alternatively, you may want to start the Server manually, eg whenever subversion is started.
There is a -f command argument that you can use to choose a particular config file like this:
jira2svn_server.exe -f c:\my_jira2svn_server.cfg
You may also want to refer to the tools/run_server.sh sample script for Unix platforms.
Two Jira2SVN Hooks are required for each Subversion and/or Git repository (and just the one for Mercurial) which are required for Jira2SVN to be enabled. The hooks and related programs are delivered in the C:\Program Files\Clearvision[Jira2SVN]\subversion_hooks and C:\Program Files\Clearvision[Jira2SVN]\git_hooks and C:\Program Files\Clearvision[Jira2SVN]\mercurial_hooks directory respectively.
The hooks need to be copied to the repository's hooks directory, and may optionally require customization for your local setup. If you have local (non Jira2SVN) Subversion/Git/Mercurial hooks to run, you may integrate these with Jira2SVN (see the .bat/shell files for more info). When a hook fires it calls the Jira2SVN_hook executable, this in turn refers to the accompanying Jira2SVN_hook.cfg file in order to know where the Jira2SVN server is running plus any other configurable options
Edit the file <svn_repository_path>\hooks\jira2svn_hook.cfg and configure the following information in the Server section:
server_ip=192.168.1.172 server_port=54321
The values provided need to match the configuration of your Change Integration server.
Configurable options are:
Each of the above option must be configured according to requirements. On unix platforms, please remember to make the hook files executable.
If you customise these scripts, please be sure to correctly handle/pass-on errors. In particular, please make sure that the return value of the pre-commit (pre-receive, pre-changegroup) hook executable is used to determine whether the transaction should be aborted. In principle, this means that if the return value of the hook executable is non-zero, the hook script itself should also return a non-zero value to ensure that the transaction is aborted.
For mercurial you will need to create a sub folder called hooks within the .hg directory, and add the changegroup hook in the hgrc file, see below.
[hooks] changegroup = C:\merc_repos\jira2svn\.hg\hooks\changegroup.bat
To use the portable hooks rather than executables, please replace pre-commit and post-commit with portable-pre-commit and portable-post-commit. Note that you must rename the portable-xxx files as otherwise they will be ignored by Subversion.
Also note that, unlike the executables, the portable version requires a set of software tools to be installed on your system. Please refer to the Appendix for details.
Jira2SVN can be customized according to your local requirements in a number of ways. This section describes all of the configuration options.
There are a number of options to control the behavior of Jira2SVN. The default options are configured to enable an enforcement policy. Using the options below, you can allow a more permissive policy for your system.
The options are set in the configuration files in a section called Options. There are options for the server, the hooks and for the clients. The server configuration options control site-wide behavior of clients, such as allowing multiple records to be selected, or allowing configuration of the subversion user id. The hook configuration options control commit behavior for that repository such as permitting anonymous commits or allowing clients to not choose a change record for their changeset. The clients can set their user id for Subversion (if this is allowed by the server).
The server and hook configuration options are detailed below. For client configuration, please refer to the Java Client User Guide.
The set of issues displayed to a Jira2SVN user are defined by the JIRA filter that you use. You can therefore freely customise this to select any issues that you like with any criteria. Note that the filter is set for the Jira2SVN Server, so is shared for all users.
You can choose between one of 2 display layouts for the Jira2SVN tab by changing the property in the jira2svn.properties file.
The default configuration pops up a GUI which allows the User to select a single JIRA record to associate with the Subversion change-set. This policy can be changed site-wide by setting the allow_multiple_choices=1 option in jira2svn_server.cfg, for example:
[Options] allow_multiple_choices=1
Normally a client will use the operating system's user id as
its Subversion user id. Depending on your local policy and setup,
you may need to allow clients to tell Jira2SVN that they have
a different user id for Subversion.
To enable this configuration option on all clients, you can set the
allow_client_svn_uid_configuration=1 option in the
server configuration file.
[Options] allow_client_svn_uid_configuration=1
Then, a client can configure their svn_uid option (see below)
The default configuration pops up a GUI which allows the User to select a JIRA issue to associate with the Subversion change-set.
Sometimes it is useful to let a user also move that issue to its next state (for example saying that development is complete, and a fix is ready to be tested).
The allow_next_state option enables this functionality for all clients. Once enabled, the clients will be presented with an enhanced popup window that allows them to optionally progress the state of a record (please see the User Guide for an image of the GUI).
PLEASE NOTE: If you enable this feature, you must also specify a configuration that specifies which JIRA workflow action should be taken for each state. This can be done through the jira_workflow_matrix option in the JIRA section.
The example below shows a workflow matrix for the default JIRA workflow. If you use customised workflows in JIRA, you will need to go to the Administration tab and select the Workflows option from the menu on the left. Then click on Steps for your workflow. State ids are shown in parentheses behind each Step Name, and Action ids are shown in parentheses behind each Transition. The jira_workflow_matrix needs to be defined such that for each state it defines what action to take. The format is jira_workflow_matrix=<state_id>:<workflow_action_id>;<state_id>:workflow_action_id;<state_id>:workflow_action_id
To enable this feature, set the allow_next_state option to 1 in the Options section of jira2svn_server.cfg, and define the workflow matrix in the jira_workflow_matrix option in the JIRA section.
[Options] allow_next_state=1 [JIRA] ; Format: jira_workflow_matrix=<state_id>:<workflow_action_id>;<state_id>:<workflow_action_id> jira_workflow_matrix=1:4;3:5;5:3;4:4;6:3
Sometimes the issue id and issue title are not enough to decide which issue to attach a change to. If this is the case, you can show more information in the Jira2SVN GUI by adding extra fields and values to the information displayed in the GUI.
You can enable this feature using the show_extra_fields configuration option in the JIRA section of the server configuration. The format is as follows:-
; Format: show_extra_fields=<field_id>[,<field_id>, ...] show_extra_fields=assignee,created
This option can be used for displaying the value of standard JIRA fields as well as custom fields. For custom fields, please specify customfield_<custom_field_id>, e.g. show_extra_fields=customfield_10020.
For standard JIRA fields, please refer to the table below for a list of JIRA field id's. Note that for standard fields you can also address sub-members of the field using the "." notation. For example, fields such as fixVersions return a dictionary containing data. You can make this information more readable by only showing the name of a fix version using show_extra_fields=fixVersions.name.
Please note that it is not advisable to add fields with large amounts of data to the extra-fields option as it can become confusing for the user.
| JIRA Field Name | Field ID |
| Project | project |
| Key | key |
| Status | status |
| Summary | summary |
| Priority | priority |
| Votes | votes |
| Reporter | reporter |
| Component/s | components |
| Created | created |
| Fix Version/s | fixVersions |
| Affects Version/s | affectsVersions |
| Issue Type | type |
| ID | id |
Jira2SVN can scan for issue id's in the Subversion log entered by the Subversion user. This is useful if you cannot or prefer not to use graphical applications such as the Jira2SVN client GUI.
You can turn this option on by adding the allow_change_ids_in_svn_log=1 option to the Options section in your server config file (the default is off).
[Options] allow_change_ids_in_svn_log=1
Issue id's need to be provided at the beginning of the log message with no preceding white spaces and followed by a space character. Multiple issue id's can be provided, with issue id's separated by semicolons. The following examples are Subversion log messages that would result in Jira issues being updated:-
TEST-17 Fixed problem TEST-10;TEST12 Fixed two problems
Note that if this option is enabled and you specify a log message that starts with a word that looks like a Jira issue id, then you can prevent Jira2SVN from scanning the log message by starting your log message with a space (or any other character):-
JAVA-2 is a great platform and fixes this problem. This problem is fixed by using the JAVA-2 platform.
Both examples above work fine as Jira2SVN will not consider JAVA-2 a Jira issue id as it does not appear at the beginning of the log message. Note that if you specify a Jira issue id at the beginning of the log message that is not part of the set of issues returned by the Jira filter, Jira2SVN will give an error.
Note that with the allow_change_ids_in_svn_log option it is possible to run Jira2SVN without a client. However, since Jira2SVN needs to be able to access the Jira server, you need to specify a default Jira username and password in the server config file. The default_jira_uid and default_jira_password is only used if the user is not logged in through a client.
default_jira_uid=myuser default_jira_password=mypassword
Please note that once these options are set, any Jira2SVN user can make use of the default user name and password. If this is not desirable, then it may be preferable to require each user to log in to the Jira2SVN server through a Jira2SVN client even when using the command line mode. You can do this by not specifying the default_jira_* options in the config file.
Note, however, that if a user is logged in through a client, Jira2SVN will pop-up the client GUI if the information provided in the Subversion log is not sufficient.
When network problems occur, clients may not be able disconnect cleanly from the server, causing the server to believe that clients are still connected and wait for a response.
With the connection_timeout setting in the Options section, you can configure the time in seconds before the server considers a connection broken.
Setting the value too low can cause clients to be disconnected on slow systems. A value that is too large can cause commits too hang until the server recognises the broken client connection.
Note that connections are checked regularly and in most cases a reasonable large timeout such as 30 or 60 seconds should be suitable.
[Options] connection_timeout=30
You can configure the time zone name and offset for commits when they are logged in Jira. By default, all commits are logged with a UTC time code.
To choose a different time zone, specify the name of the time zone in svn_timezone_label and configure the offset from UTC (Coordinated Universal time) in hours. For example, for CET specify svn_timezone_offset=+1 or for PST specify svn_timezone_offset=-7.
When configuring the name of the time zone, please use standard names such as CET, PST or GMT as otherwise the Jira2SVN Jira plugin will not be able to translate time stamps correctly.
[Options] svn_timezone_offset=+1 svn_timezone_label=CET
A user who is logged in to the Jira2SVN system normally
must choose a record to go with their changeset.
If they cancel their choice, Jira2SVN will
abort the Subversion commit.
If you want to allow them to optionally not select
any of their current change records
and 'cancel' their choice in the GUI (ie. allow commits without any change record, you can set this option.
WARNING: Enabling this will mean that some changes are NOT recorded in your change control system!
[Options] allow_commit_without_change_id=0
Default behaviour is to check that a user has logged on to the
Jira2SVN Server, and to abort any commits from users who are not
yet logged on (a policy-'enforcing' mode). You can disable this behaviour
here (for example if some of your users do not use change records)
WARNING: this will mean that those users not running a Client
will NOT be using this system to correlate Subversion
with your change control system, and effectively bypassing Jira2SVN altogether!
[Options] allow_anonymous_commits=1
Normally, if an error occurs in the system, Jira2SVN will try to
abort the commit.
If you want to let the commit proceed (for example
as a temporary measure until you fix a system problem), you
can set this option:
[Options] allow_commit_on_error=0
Note that this is not guaranteed to work as it depends on the exact problem that is occurring, so, please use with caution.
You can configure Jira2SVN to add issue ids to the subversion log message. If you enable this option and commit a change, Jira2SVN will add the ids of all issues chosen by the user to the front of the log message.
This has two advantages:
[Options] log_issue_ids_in_svn=1
Please note this feature is not supported with Git repositories.
To check that a Jira2SVN client or server is running on Windows, open the Windows Task Manager. You should see 2 entries for the server (on a server machine). To kill the process, right click on the process in the Processes tab and select 'End Process Tree' (to kill both processes at once). If the process is not running, check your log file for any errors. On Linux, use ps -ef | grep jira2svn - these processes can be safely killed.
On a client machine running the Java client, you should see the client icon in the system tray. Please refer to the Java Client User Guide for details.
To investigate setup problems, it can be helpful to increase the logging level from the default of 'Warning' to 'INFO' (see jira2svn.cfg)
Note that when an error occurs, the default behavior is to abort the commit. Some possible reasons are:
svn commit myfile.txt --username engineer
Note that you can use this command, but Subversion still works anonymously if you have asked it to (eg using svnserve with anon_access=write).
The config files use unix line-endings, so please be careful to use a well-behaved text editor such as http://cream.sourceforge.net/ or Wordpad rather than Notepad or MS Word.
If you have problems with the JIRA plugin, please check the JIRA log files for any reported errors. It will help to have the logging level for your application server set to INFO or DEBUG. Also, check the status of the plugin in the JIRA Administration panel.
If you experience any issues during the installation please report your issues via the Clearvision Support Centre, which can be found at http://www.clearvision-cm.com/support-home/support-center.html.
The Change Integration product suite, which currently provides solutions for CQ2SVN, Jira2Svn, CodeBeamer2Svn and Trac2Svn, has been extended to support Git and Mercurial managed repositories.
The principle for Git and Mercurial repositories follows along the same lines as the Subversion-based solution. Hooks are installed in the Git/Mercurial repository which fire on changes to the repository and prompt the user to select the records to attach to the new revision.
Each user runs a client process, which prompts the user for a record id when changes are applied to the repository. Note that even if you work with multiple clones of the same Git/Mercurial repository, you only need to run one client process as the connection of the client is with the server for the central repository and not your clone.
There are some notable differences between Subversion and Git/Mercurial when integrating with change management systems using the Clearvision Change Integration product suite. The most notable change is that with Git you will not be prompted for a change record to attach on every commit. It is not until the point that changes are pushed back into a central repository that they become visible to users of the same repository.
It is therefore on the push operation that the Change Integration solution triggers and prompts the user to select a record to attach to the change-set being pushed to the server.
If you are pushing a number of commits in one operation, you will only receive one pop-up, and the selected change record(s) will be associated with all the commits being pushed.
Note that due to the nature of the products, the Git/Mercurial integration is only useful in environments where users push into a central repository. For more distributed development environments with informal sharing of repositories it would not be appropriate to connect these informal and potentially transient repositories to a central change management repository.
The same server process can be used as the target for Git, Mercurial as well as Subversion hooks. This makes it possible for developers to use the same client process to receive pop-ups for pushes to the central repository on the Git and Mercurial side and commits to a Subversion repository on the Subversion side.
Note that in this scenario the same server process is being used, meaning that Subversion commits and Git/Mercurial pushes will present the user with the same list of issues to attach to a change-set. If you need to use a different list of issues or connect to a different change management repository, you will need to use multiple server processes.
Please install the server and client elements of the product as per the normal installation instructions. Once the product is installed, you can install the Git hooks in a bare repository as follows:
Please install the server and client elements of the product as per the normal installation instructions. Once the product is installed, you can install the Mercurial hooks in the Mercurial repository as follows:
Change Integration provides a special version of the Subversion hooks, which is independent of the operating system. This allows you to run Subversion on virtually any platform. The Git and Mercurial hooks are not tied to a specific version of Git and Mercurial. However, please note the minimum version of Git supported.
We recommend that you only use this if your platform is not supported by the executables as the installation is more involved.
To use the Portable Hooks, you must download the version that matches your version of Python. There are also a number of 'pre-requisite packages that must be installed.
These packages may already be installed on your system, but if they are not, please note that the software required is Open Source and can be downloaded and compiled from source as required. Note that on Linux, Sun and Mac, binary packages for your OS distribution may also be available.
Prerequisite Packages:-
Note that the version numbers indicated above are the versions of the tools Jira2SVN has been tested with. Jira2SVN may well work with other versions of the tools, but this cannot be guaranteed. Please make sure that the product works in your environment before purchase. An evaluation licence can be made available for that purpose.
Please refer to the appendix for guides on installing pre-requisite software for specific platforms.
Sun Solaris 10
This appendix gives guidance on installing prerequisite tools for portable hooks on a Solaris 10 system. Please note that the instructions below are for guidance only and your system may require different steps.
Python 2.4 is available on the Solaris CD, and other versions (including python 2.5) are available from Sunfreeware.com. These use the standard Sun pkgadd.
We would recommend using python 2.5 if possible.
This package has long file names, therefore it *requires 'gtar' * to be unpacked.
Twisted requires the interfaces package in Zope.
This package has long file names, therefore it *requires 'gtar' * to be unpacked.
Note that PySVN requires GNU's version of make, "gmake".
The version of gcc that we used had a problem with finding the right linker.
GCC has http://gcc.gnu.org/faq.html#gas (for as, ld, etc.). Our version was missing the path to the GNU linker, but had the Sun linker, so failed with an invalid (GNU-specific parameter, ie --rpath).
To work around this problem, we moved /use/css temporarily (see below)
Copyright (c) 2011 Clearvision CM All Rights Reserved Registered in England No. 5643578 VAT Registration No. UK881364801 Registered Address Laurel Farm, Winters Hill, Durley Southampton, SO32 2AH