Documentation

The PERSPEQTIVE SVN-Connector for Jira script offers a simple way to display SVN commit references within any Jira ticket. The script reads configuration settings from an XML configuration file to gather the necessary information for accessing SVN and Jira services.

Installation

  • Download the script perspeqtive-svn-connector-for-jira.phar.
  • Ensure that PHP 8.2 with the curl, mbstring, libxml and simplexml extensions is installed on your system.
  • Confirm that the SVN client is callable from the command line.
  • Execute the script in the command line.

Requirements

  • PHP 8.2 with curl, mbstring, libxml and simplexml modules
  • PHP 8.2 needs to run the exec command
  • A user with read access to your SVN repositories

Usage

Run the script with the following as described:

    

php perspeqtive-svn-connector-for-jira.phar [OPTIONS]

Options

  • -h, --help: Shows the help message.
  • -c, --config: Sets the path to the configuration file. Takes a filepath as argument.
  • -d, --debug: Writes debug information to the file debug.log during execution.

Example

    

php perspeqtive-svn-connector-for-jira.phar -c "config.xml" --debug

Execution as cronjob

For regular execution and updating of Jira ticket references, the script can be set up as a cronjob.

Example of setting up a cronjob:

  1. Edit the crontab:
    Open the crontab file by running crontab -e in the terminal.
  2. Add an entry for the script:
    Example: Execute the script every minute to ensure timely processing of all changes.
    /usr/bin/php /path/to/script/perspeqtive-svn-connector-for-jira.phar 
    Here, /usr/bin/php is the path to the PHP installation, and /path/to/script/perspeqtive-svn-connector-for-jira.phar is the path to the script.
  3. Save and close:
    Save the changes in the crontab file and close the editor.

Note that the path to the PHP installation and script needs to be adjusted according to your system. Setting it up as a cron job will automatically run the script at the specified times to check for updates in the SVN repositories and search for Jira ticket references.

Configuration file

The script expects a XML configuration file. By default, it should be named config.xml and be placed right beside the phar-script.

This is an example, how your config file could look like:

    

<?xml version="1.0" encoding="UTF-8" ?>
<configuration>
   <jira>
       <tenant>https://your-tenant.atlassian.net</tenant>
       <auth>
           <email>your-email@your-company.com</email>
           <token>Your jira token. Do not use your password here.</token>
       </auth>
   </jira>
   
   <subversion>
       <viewer>
           <pattern>https://svn.my-domain.com/repos/{name}/info?revision={revision}</pattern>
       </viewer>
       <credentials>
           <username></username>
           <password></password>
       </credentials>
       <repositories>
           <repository>
               <url>https://our-repositories.local/test</url>
           </repository>
           <repository>
               <url>file:///home/svn/weiteres-repo</url>
           </repository>
       </repositories>
   </subversion>
</configuration>

Jira configuration

XML-FieldRequiredDescription
<tenant>yesThe URL to your Jira instance.
<auth>yesAuthentication information for accessing Jira.
<email>yesYour email address.
<token>yesYour token. For guidance on creation, refer to the paragraph about Jira tokens.

SVN configuration

Viewer

This block is optional. When filled, clicking on the referenced revision within Jira will automatically direct to the revision's page. If the block isn't configured, there won't be a direct link to the revision or your repository at all.

XML-FieldRequiredDescription
<viewer>noThe SVN viewer configuration
<pattern>yes, if viewer is setYou can specify a URL pattern. The placeholders {name} and {revision} will be replaced here. {name} represents the repository's base name.

Credentials

At times, accessing repositories may require a username/password. Hence, this optional block can be used. Ensure that the user has only read access to the repositories. That's all the script needs.

Ideally, it's better to access repositories through other means, like running the script itself with a user already having read access to the repositories, using environment variables, etc.

XML-FieldRequiredDescription
<credentials>noThe credentials for accessing the SVN repositories.
<username>noThe username for SVN access.
<password>noThe password for SVN access.

Repositories

Any number of repositories can be listed here.

XML-FieldRequiredDescription
<repositories>yesA list of SVN repositories.
<repository>yesAn individual repository.
<url>yesAn individual repository.

 

Jira token

A token can be created in your account at https://id.atlassian.com/manage-profile/security/api-tokens. Click on "Create API token," give it a meaningful label like "SVN-Connector for Jira" and then copy the generated token into the configuration file. Done.

Data security

The script adheres to data minimization principles. Only necessary data about your commits is retrieved and sent to the Jira instance. The data is not transmitted to third parties or the provider; it's solely stored as meta-information within the Jira ticket. PERSPEQTIVE never gains access to the data at any point.