Svn Gateway documentation

Internet

When you install the add-on in JIRA® Cloud, a Configure button appears in the Administration / Add-ons / Manage Add-ons / Svn Gateway

In order to ask SvnGateway to retrieve the Subversion commits from the Internet, select the Public - Internet option:

Configure

In this mode, you only need to provide Svn Gateway with the following information:

  • Nick name: Allows you to differentiate between your different repositories, if you have more than one [optional].
  • Subversion URL: complete path to your subversion repository.
  • Username: the username to access the SVN repository
  • Password: the password of that user to access the SVN repository.
  • Subversion Viewer URL: this is the prefix to add before the revision number, to access your SVN viewer. Many SVN hosting system include a way to see details of a revision. We will add this complete URL and follow it with the revision number so that you can quickly access your SVN changes [optional].

Note: If you have a repository on the Internet, in which some access rules restrict access based on IP addresses, you should add the following IP address:

  • 5.196.82.16

to the list of authorized IP addresses

Intranet

If you prefer sending the data to SvnGateway from your Intranet, you select the Private - Intranet option:

Configure

In this menu, you can see the key that you will have to use to configure SvnFeeder below

You can also enter a prefix for the links to the Svn Viewer application that you have on your intranet.

SvnFeeder

You will have to install a small Java program (SvnFeeder) to poll the Subversion server and send the commit comments and list of files to Svn Gateway.

You will need Java 1.8+ to run that program. Our add-on server uses https with TLS 1.2, which means that Java versions like 1.7 doesn't work with it.

The configuration is done in a simple XML file:

Single repository

configuration file example
<svn_feeder_configuration>
   <svn_repository key='ip...21' stop_on_copy='1' first_rev='-1'>
       <url>https://xxx.example.com/svn_dev</url>
       <username>xx</username>
       <password>xx</password>
   </svn_repository>
</svn_feeder_configuration>

Note that the key (ip...21 in the markup above) has to be replaced by the key assigned to your repository in the Repository Settings screen above.

Optional attributes:

  • stop_on_copy: set to 1 or 0. For details about usage, please refer to Subversion documentation
  • first_rev: Use this attribute if you only want to have the last part of a branch to be used for the synchronization. If the attribute is not present, SvnFeeder will take the whole branch

Initial revision

In some special cases, your path inside the subversion repository may not start with revision 0 or 1, but thousands. 
In this case, the lookup for revisions will fail and you will get a message like this:

ERROR SvnFeeder – Exception [svn: E160013: (path) path not found: 404 Not Found (path)

In this case, you will have to explain the feeder what is the first revision number it should take into account. This is done by adding a first_rev attribute:

<svn_feeder_configuration>
   <svn_repository key='ip...21' first_rev='101002' >
       <url>https://xxx.example.com/svn_dev</url>
       <username>xx</username>
       <password>xx</password>
       <nick>Dev</nick>
       <svn_viewer>http://10.0.0.45/SvnViewer/svn_dev/rev/</svn_viewer>
   </svn_repository>
</svn_feeder_configuration>

Program parameters

SvnFeeder is launched with the following command:

command line
java -jar SvnFeeder.jar -c configfile [-loop][-reset][-cmdLine]


Optional arguments

  • -loop: when specified, SvnFeeder will stay in memory and run an update every minute
  • -reset: if specified, SvnFeeder will start by requesting Svn Gateway to remove all known data about the repositories described in this configuration file. 
    This is useful if you change from one repository to another, or from a trunk to a branch
  • -cmdLine: if specified, instructs the feeder to use the command line svn command instead of the built-in (Java) library

Subversion 1.9

The Svnkit Java library that is linked with SvnFeeder is not compatible with Subversion 1.9 or higher.

If this is your case, you have to use the -cmdLine argument as described above, so that SvnFeeder calls the local command-line client program, which must be compatible with your subversion server.

Windows / Linux / Mac OS/X

Here are the steps to install SvnFeeder under Windows, Linux or Mac OS/X:

  • Ensure you have Java 7 or higher installed
  • Download SvnFeeder.jar
  • Create a folder for installation
  • Move SvnFeeder.jar to this folder
  • Create the configuration file in this folder

  • Run the feeder:

    java -jar SvnFeeder.jar -c configfile -loop &

    this will run the SvnFeeder in the background, and update Svn Gateway every minute. Then you can call this script from /etc/rc.local for example under Linux.

You can also use the post-commit technique to launch this tool only after each repository commit. 
See a description of the steps below on this page

Multiple repositories

If you need to use more than one repository, you can use this button:
more keys 
to add one more key to your set of keys. You will then be able to use the above setup for all the different keys you have.

If you chose to use the Intranet mode, the configuration file you write will then look like this:

configuration files example
<svn_feeder_configuration>
   <svn_repository key='ip...21'>
       <url>https://xxx.example.com/svn_dev</url>
       <username>xx</username>
       <password>xx</password>
       <nick>Dev</nick>
       <svn_viewer>http://10.0.0.45/SvnViewer/svn_dev/rev/</svn_viewer>
   </svn_repository>
   <svn_repository key='ip...21/2'>
       <url>https://xxx.example.com/svn_marketing</url>
       <username>xx</username>
       <password>xx</password>
       <nick>Marketing</nick>
       <svn_viewer>http://10.0.0.45/SvnViewer/svn_marketing/rev/</svn_viewer>
   </svn_repository>
</svn_feeder_configuration>

The same optional attributes described above can be used for each repository

Subversion server commit hooks

pre-commit

If you want the force your users to enter a commit comment containing a valid JIRA issue key in each commits, you can do so by using the following recipes:

  1. Add this code to the pre-commit file on the subversion server:
    For Linux:

    REPOS="$1"
TXN="$2"
TMP=`mktemp`
/usr/bin/svnlook log -t $TXN $REPOS > $TMP
java -jar /pathtosvnfeeder/SvnFeeder.jar -c /pathtoconfigfile/configFile -checkjira "$REPOS" "$TMP" || exit1

    For Windows with VisualSVN (code contributed by Antenor):

    set REPOS=%1
set TXN=%2
set SVNLOOK="%VISUALSVN_SERVER%\bin\svnlook.exe"
set SVNFEEDER= "pathtosvnfeeder\SvnFeeder.jar"
set FEEDERCONF= "pathtoconfigfile\SvnFeederConfig.xml"
set TEMP=%VISUALSVN_SERVER%jira%TXN%.log
%SVNLOOK% log -t %TXN% %REPOS% >  "%TEMP%"
java -jar %SVNFEEDER%  -c %FEEDERCONF%   -checkjira "%REPOS%" "%TEMP%"
if %errorlevel% gtr 0 (goto error_exit) else goto normal_exit
:error_exit
del "%TEMP%"
exit 1
:normal_exit
del "%TEMP%"
exit 0


    where:

    • pathtosvnfeeder is the absolute directory to the SvnFeeder java program
    • and pathtoconfigfile the absolute directory to the SvnFeeder configuration file.
    This is the only mandatory step. When you've done this, the subversion server will call our SvnFeeder utility before each commit and SvnFeeder will send a request to our add-on asking if the JIRA issues keys detected in the commit message exist.
    • If at least one of such key is found the commit is accepted
    • otherwise it is refused.

  2. If you have want to restrict the choice of JIRA projects to only a list of projects, you can add the following XML element in the configuration file:

    <svn_feeder_configuration>
   <pre_commit projects='X,Y,Z' />
   <svn_repository key='ip...21'>
            ...
   </svn_repository>
</svn_feeder_configuration>

    with X,Y,Z the list of projects you want to allow. All other projects will not be accepted. If a commit contains at least one of the authorized projects's existing issues, the commit will be accepted. 

  3. If you have many repositories, with one or more JIRA project matching each repository, you can add the following marking in the configuration file to specify the correspondence:

    <svn_feeder_configuration>
   <svn_repository key='ip...21'>
       <pre_commit projects='X,Y,Z' local_svn='pathtosvn' />
            ...
   </svn_repository>
</svn_feeder_configuration>

    Note that in this case the pre_commit element is inside the svn_repository element. You can specify different pre_commit elements for every subversion repository. 

    In order for the matching to work, you also need to add the local_svn attribute: it must contain the server local path to the repository 
    One of our customers has 40+ repositories, and one JIRA project for each repository. They just added a pre_commit element to each of their repository to ensure that commits cannot be done to the wrong project.

  4. Restriction on JIRA status: you can also add that only some JIRA issues status are accepted when you commit. 
    This is also done with a pre_commit XML element but this time with the status attribute:

    <svn_feeder_configuration>
   <pre_commit projects='X,Y,Z' status='Open,In Progress' />
   <svn_repository key='ip...21'>
            ...
   </svn_repository>
</svn_feeder_configuration>

    In this case, only the issues with status Open or In Progress are accepted by the pre-commit. The status attribute is independent of the projects attribute. Both can be specified globally or by project.

  5. If you have other special requests for the pre-commit rules, we can probably manage to implement them, don't hesitate to come back to us.

post-commit

You can use SvnFeeder in a smarter way than the -loop attribute that will ping the subversion server every minute. 
Add this code to the post-commit file on the subversion server:

java -jar /pathtosvnfeeder/SvnFeeder.jar -c /pathtoconfigfile/configFile

where:

  • pathtosvnfeeder is the absolute directory to the SvnFeeder java program
  • and pathtoconfigfile the absolute directory to the SvnFeeder configuration file.


The SvnFeeder program will only be called after a successful commit to the repository. 
This will be more efficient than asking every minute, although the bandwidth of such query is really low.

API

Another way to feed our add-on is to send the commit details through a small REST API.
This will allow you for example to send data only on post commit hooks instead of the 1 minute polling.
Ask us to have access to the API definition.

Downloads

The Java program to install is here: https://assets.matrixreq.com/SvnFeeder.jar 
 it works under Windows, Linux, OS/X.

How to use Svn Gateway when it has been configured

The link between JIRA and subversion is based on the commit comments: you need to add the ID of the JIRA issue.

The commit comment can contain any number of JIRA issues, and they can be anywhere on the comment.

All the following links will be recognized:

  • WEB-123
  • WEB-234: fixing bug
  • WEB-456, WEB457: remove bad code
  • Fixing nasty bug described in SERVER-123

The links between the JIRA issue and the SVN commits is listed in the Svn Gateway tab:

When you click on a commit, the list of files is shown:

You can also use the Svn Activity Screen button at the right of the screen: this gives you access to the whole list of commits, more recent first:


HELP / Contact

Don't hesitate to contact us to assist in the installation.


Legal

Terms & Conditions of Site Use

Thank you for using Matrix Requirements' Jira® Svn or Svn Gateway add-ons. This page states the terms and conditions under which you may use the add-on. It is important that you read this page carefully because by using our web site you agree to be bound, without limitation or qualification, by these terms. If you do not accept any of the terms stated here then do not use the add-on. This add-on may, in its sole discretion, modify or revise these terms at any time by updating this web page. You are bound by any such modification or revision.

Disclaimer of Damages

Use of our add-on is at all times "at your own risk." If you are dissatisfied with any of the materials, any of these terms and conditions, the add-on's privacy policy, or any other policies, your only remedy is to discontinue use of our add-on. In no event shall the add-on, or its suppliers, be liable to any user or third party, for any damages whatsoever resulting from the use or inability to use the add-on or the material on that site, whether based on warranty, contract, tort, or any other legal theory, and whether or not the add-on manufacturer is advised of the possibility of such damages. The definition of damages under this provision include, but are not limited to, indirect or consequential damages, any loss or damage arising from loss of data, and any lost profits arising out of or in connection with the use of this add-on.

Copyright Protection

The contents of the add-on are protected by copyright and other laws in both the United States and elsewhere. Copyrighted materials include content owned or controlled by the manufacturer and includes the concept, programming, layout, images, and design. You may not, except with our express written permission, distribute or commercially exploit our copyrighted content.

This add-on does not claim ownership to anything submitted to it. Submitting something to this add-on does not place it into the public domain. The copyright owner retains full ownership of any work submitted to this add-on.

Data Access

By using this add-on, you allow legally the add-on server and the add-on operators to access the Subversion repository to which you ask the add-on to use. Neither the add-on server code, nor any of the procedure involved in the development and testing will actually access the subversion data files. The only requests done to the Subversion repositories are a query for the list of commits, their date, authors, comments, and file names involved.

Data Retention

If you setup the add-on to access Subversion repositories through the Internet, Svn Gateway will retain your SVN credientials information.

If you select the SvnFeeder option to send data to Svn Gateway from your intranet, these credentials are never communicated to us.

Svn Gateway will retain the list of commits made on your Subversion repository on our servers as long as you request us to do so. You may delete data from your account, or delete your entire account at any time, by un-installing the add-on from JIRA®.

This add-on maintains backups of all data for use in recovering from a catastrophic failure. These backups are maintained in a secure location for approximately 1 month before being recycled. Therefore, the credentials you stored in the add-on and the list of Subversion commits will remain in our backups for approximately 1 month before being permanently deleted.

Warranty Policy

Matrix Requirements (matrixreq.com) Svn Gateway and material therein are provided without warranties of any kind, whether express or implied. The add-on, to the fullest extent permitted by law, disclaims all warranties, including but not limited to warranties of title, fitness for a particular purpose, merchantability and non-infringement of proprietary or third party rights. The add-on makes no warranties about the accuracy or reliability of the material, services, text, graphics, and/or links. The add-on does not warrant that it will operate error-free or that this add-on or its server are free of computer viruses or other harmful items. If your use of our add-on or the material on this site results in the need for servicing or replacing equipment or data, the add-on is not responsible for those costs.

Copyright Violations

At its discretion, this site may remove any material posted on our add-on that infringes on the rights of others. If you believe that your work has been used improperly or your copyrights have been violated we encourage you to contact us.

Indemnity

By using this add-on you agree to defend, indemnify, and hold harmless the add-on, its officers, directors, employees and agents, from any claims, actions or demands, including without limitation reasonable legal and accounting fees, alleging or resulting from your use of the material or your breach of the terms of this agreement. The add-on shall provide notice to you promptly of any such claim, suit, or proceeding and shall reasonably assist you, at your expense, in defending any such claim, suit or proceeding.

If any provision of this agreement is found to be invalid by any court having competent jurisdiction, the invalidity of such provision shall not affect the validity of the remaining provisions of this agreement, which shall remain in full force and effect. No waiver of any term of this agreement shall be deemed a further or continuing waiver of such term or any other term. This agreement constitutes the entire agreement between you and matrixreq.com. Any changes to this agreement must be made in writing and signed by an authorized representative of the add-on.


Search