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, readline, libxml, simplexml and zlib 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, readline, libxml, simplexml and zlib modules
- PHP 8.2 needs to run the exec command
- A user with read access to your SVN repositories
Usage
Run the script with any of the following options 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.-g,--debug-file: Set the filename to the debug log file. Can be either a name or a path. Default isdebug.log-d,--debug: Writes debug information to the filedebug.logduring execution.-w,--wipe-jira: Reads all commits from your configured repositories and removes them from your tickets. (You have to type the word "yes" to confirm)-l,--limit: Limits the amount of revisions per repository, which are processed in a single run. 0 equals unlimited.-r,--rescan: Rescans a given revision. Per default a single revision is rescanned. When using in conjunction with the --limit parameter, multiple subsequent revisions can be scanned.-s,--rebuild-search-metadata: After the regular run, backfills the search metadata from the SVN history. Optional value: the number of revisions per repository and run. Default:1000-m,--search-metadata-database: Path to the file that stores the backfill progress. Default:search-metadata-db.json
Note: The value of --rebuild-search-metadata is optional. You must attach it directly to the option: write --rebuild-search-metadata=5000 or -s5000. With a space, as in -s 5000, the value is ignored and the default of 1000 is used.
Examples
Default usage
php perspeqtive-svn-connector-for-jira.phar
Extended usage
Run the phar file to read all new commits from all repositories configured in "config.xml" and save debug information at the debug.log-file.
php perspeqtive-svn-connector-for-jira.phar -c "config.xml" --debug
Rescanning items
Rescan revisions 150, 151, 152 from repository https://svn.lan/my-repo. (This repositoriy needs to be configured in the config.xml-file)
php perspeqtive-svn-connector-for-jira.phar -r https://svn.lan/my-repo:150 -l 3
Regular run, then backfill the search metadata in steps of 5000 revisions per repository:
php perspeqtive-svn-connector-for-jira.phar --rebuild-search-metadata=5000
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:
- Edit the crontab:
Open the crontab file by runningcrontab -ein the terminal. - 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/phpis the path to the PHP installation, and/path/to/script/perspeqtive-svn-connector-for-jira.pharis the path to the script. - 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>
<tokentype>DEFAULT</tokentype>
</auth>
<large-dataset-mode>MODE_PURGE_OLD_COMMITS</large-dataset-mode>
</jira>
<subversion>
<viewer>
<pattern>https://svn.my-domain.com/repos/{name}/info?revision={revision}</pattern>
<file-pattern>https://svn.my-domain.com/repos/{filepath}/info?revision={revision}</file-pattern>
</viewer>
<credentials>
<username></username>
<password></password>
</credentials>
<repositories>
<repository>
<url>https://our-repositories.local/test</url>
</repository>
</repositories>
</subversion>
</configuration>
Jira configuration
| XML-Field | Required | Description |
|---|---|---|
<tenant> | yes | The URL to your Jira instance. |
<auth> | yes | Authentication information for accessing Jira. |
<email> | yes | Your email address. |
<token> | yes | Your token. For guidance on creation, refer to the paragraph about Jira tokens. |
<tokentype> | no | Selects, what kind of token you are using. There are two possible options:DEFAULT: When you are using a simple API-token, the inserted token type should be DEFAULTSCOPED: If you are using a scoped API-token, wether it be a personal personal one or for a service user, please insert SCOPEDDefault is DEFAULT |
<large-dataset-mode> | no | Selects the strategy to purge really large datasets related to a ticket. There are currently 2 modes: MODE_PURGE_FILES: If the Jira API responds with an indication, that the transmitted data is too big. the SVN-Connector script purges the associated files of all revisions of the current Jira ticket and keeps the revision list complete.MODE_PURGE_OLD_COMMITS: If the Jira API responds with an indication, that the transmitted data is too big. older commits associated to this ticket are beeing removed, until the information is small enough to fit into the Jira issue.Default is MODE_PURGE_FILES |
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-Field | Required | Description |
|---|---|---|
<viewer> | no | The SVN viewer configuration |
<pattern> | yes, if viewer is set | You can specify a URL pattern. The placeholders {name} and {revision} will be replaced here. {name} represents the repository's base name. |
<file-pattern> | no | You can specify a pattern, to explicitly link to a revision of your file. Additionally to the pattern placeholders, you can use the {filepath} placeholder to reference the filepath in details view. If you don't specify this value, the files in the details view link to the path specified in the <pattern> section. |
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-Field | Required | Description |
|---|---|---|
<credentials> | no | The credentials for accessing the SVN repositories. |
<username> | no | The username for SVN access. |
<password> | no | The password for SVN access. |
Repositories
Any number of repositories can be listed here.
| XML-Field | Required | Description |
|---|---|---|
<repositories> | yes | A list of SVN repositories. |
<repository> | yes | An individual repository. Each SVN-repository needs its <repository> section. You can place any number of repositories you need. |
<url> | yes | An individual repository url. The url of the SVN-repositories. There must be exactly one url section inside of each repository section. |
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.
Scoped Jira API-tokens
When using "SVN-Connector for Jira" in a secured environment, you might want to use scoped API token. This is perfectly fine. Please keep in mind, to add the appropriate tokentype section as mentioned above.
The required scopes for "granular Scopes" need a least to be:
read:issue.property:jirawrite:issue.property:jira
How to Query for SVN Commits
The SVN Connector app registers the following JQL fields for you to query for:
| JQL field | Type | Supported operators |
|---|---|---|
svnHasCommits | number | =, !=, >, >=, <, <=, IN, NOT IN, IS EMPTY, IS NOT EMPTY |
svnRepository | string | =, !=, IN, NOT IN, IS EMPTY, IS NOT EMPTY |
svnRevision | string | =, !=, IN, NOT IN, IS EMPTY, IS NOT EMPTY |
svnCommit | string | =, !=, IN, NOT IN, IS EMPTY, IS NOT EMPTY |
repositories, revisions and commitKeys are lists. A condition such as svnRepository = "backend" matches as soon as one entry in the list matches.
Tickets with and without commits
Tickets with at least one SVN commit:
svnHasCommits = 1
Tickets without any SVN commit. Tickets that were never touched by the script have no property, so you need both conditions:
svnHasCommits IS EMPTY OR svnHasCommits = 0
Typical use, e.g. for a release check: resolved tickets in a project that have no commit:
project = SHOP AND statusCategory = Done AND (svnHasCommits IS EMPTY OR svnHasCommits = 0)
These results are only reliable after the backfill has finished.
By repository
Tickets with commits in a specific repository:
svnRepository = "backend"
Tickets with commits in one of several repositories:
svnRepository IN ("backend", "frontend")
Tickets with commits in both repositories:
svnRepository = "backend" AND svnRepository = "frontend"
Tickets with commits that have no commit in a specific repository:
svnHasCommits = 1 AND svnRepository != "frontend"
By revision
Tickets that reference a specific revision:
svnRevision = "1852"
Tickets that reference one of several revisions:
svnRevision IN ("1852", "1853", "2040")
Revision numbers are not unique across repositories. Revision 1852 can exist in every repository. If you work with more than one repository, use svnCommit.
By commit (repository + revision)
Tickets for exactly one commit:
svnCommit = "backend@1852"
Tickets for several commits, e.g. all tickets touched by a merge:
svnCommit IN ("backend@1852", "backend@1853", "frontend@2040")
Combining with other JQL
The fields work with any other JQL clause, for example:
project = SHOP AND fixVersion = "2.4.0" AND svnRepository = "backend" ORDER BY updated DESC
assignee = currentUser() AND svnHasCommits = 1 AND resolution = Unresolved
Limitations
- No ranges for revisions: Revisions are stored as text, so
svnRevision > "1000"does not work. To find a range, list the revisions withIN. - No wildcards:
~(contains) is not supported. Values must match exactly and are case-sensitive. - Truncated tickets: On tickets with a very large number of commits (
truncated = 1),svnRevision(and possiblysvnCommit) may no longer find every commit.svnHasCommitsandsvnRepositoryare always complete. - Indexing delay: Jira updates its search index asynchronously. A commit may take a short while to show up in search results.
Configuring the appearance
When migrating from other tools to "SVN-Connector for Jira" you might be used to a certain view or order of information inside the SVN commit list panel. You can customize this view by visiting the "Manage apps" section of your Jira instance and selecting "Configure" behind the 3 dots.
You will be taken to the configuration page, where you can sort the order of the displayed fields, as well as toggling,whether is beeing displayed in the panel at all.
Additionally, you can toggle, whether a certain field is linked to your repository viewer or not.
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.