Integrating JIRA with CVS and ViewCVS

JIRA retrieves the CVS commit information for an issue by parsing the output of the 'cvs rlog' (or cvs log) command of each associated CVS module and scanning it for the issue's key. If an issue key is found in the commit message, the commit message is displayed on the Version Control tab for the issue.

If you have allowed JIRA to automatically synchronise with the CVS repository, JIRA will periodically run the 'cvs rlog' command for the module and store the results in a file which path is specified by the module's Log File Path attribute. The file is then parsed for commit information.

If you have chosen to update the log manually, JIRA will only periodically parse the CVS log specified by the module's Log File Path attribute.

As JIRA parses the module's CVS log and keeps relevant commits in memory, the required memory for JIRA is relative to the size of the CVS module.

Please note:

• Currently, JIRA is able to retrieve CVS log data via local access, pserver protocol or ssh (ext method). If your CVS is not reachable by these methods you can disable automatic log retrieval (see below).
• If you would like JIRA to automatically keep synchronised with your CVS repository, the communication between JIRA and the CVS server might be fairly bandwidth intensive as JIRA will periodically retrieve the CVS module's log data from the CVS repository. If this is causing problems, consider adjusting the frequency (see below) or disabling CVS log retrieval.
• JIRA loads and parses the output of the 'cvs log' command for each CVS module and keeps 'relevant' commits in memory. Therefore JIRA's memory requirements depend on the number of relevant commits found in the CVS module. Relevant commits are CVS commits which have at least one potential JIRA key in their commit messages.
• Only commit messages which contain a possible JIRA issue key are linked to an issue.
• JIRA's 'System encoding' is used when parsing the CVS logs, so it needs to match that of the CVS log. The system encoding can be seen at Admin -> System -> System Info. See also how to set the system encoding.

A CVS 'module' refers to a top-level directory in a CVS repository. To create a CVS module:

1. Create or decide which existing directory will be used to store CVS module's log data (The file with the output of the 'cvs log' command). JIRA must have read and write access to the directory. The write access is required even if you choose to update the CVS log manually as JIRA needs to use this directory to create a lock file in order to synchronise access to the CVS module's log.
2. Log in as a user with the 'JIRA System Administrators' global permission.

3. Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard:

   

4. On the panel on the left, expand the sub-menu titled 'Global Settings' if it is not open already. Click on the link labelled 'CVS Modules'. This should bring up the 'CVS Modules' page.
5. Click on the 'Add new CVS module' link on this page.

6. This will bring up the 'Add CVS Module' page.

   

   Fill in as follows:

   1. For Name put a short descriptive name, possibly just the name of the CVS module as it appears in your CVS repository.
   2. (Optional) For Description put a short phrase that describes this CVS module.
   3. Specify CVS Root that will be used to retrieve the CVS module's log or was used to retrieve the log. The CVS Root is needed while parsing the log data so it is required even if you choose to retrieve CVS log manually. Please provide 'full' CVS Root details. For example:
      • /some/local/path (for local repository access)
      • :pserver:username@hostname:port/some/path (for pserver access)
      • :ext:username@hostname:/some/path (for ssh access)
      If JIRA finds trouble understanding your local CVS Root (e.g. on Windows systems) please prefix the path with :local:. For example, :local:d:\some\path.

   4. For Module Name specify the name of the module as it is called in the CVS repository. This will usually be the top-level directory (eg. myproject), but can also include subdirectories (myproject/subproject/src/java) - basically anything that can be parsed to a cvs checkout command.

      This information is required to retrieve the CVS log as well as to parse it, so you will need to provide the module's CVS name even if you choose to retrieve the CVS log manually.

   5. For Log Retrieval choose whether you would like JIRA to automatically synchonise with the CVS repository. If you choose 'Automatically retrieve the CVS log', JIRA will periodically retrieve the CVS log for the module automatically and then parse it for commit information. If you choose 'I would like to update the log myself', JIRA will not retrieve the log, but will periodically just parse it. If you choose this option you will need to update the CVS log by other means (e.g. manually or using a scheduled script) to keep the CVS information in JIRA current.
   6. For Log File Path specify the full path to the file that will contain the CVS log data. This file should be located in a directory mentioned in step 1. If you would like JIRA to periodically update the contents of the log this file does not need to exist at the moment, as JIRA will automatically create it. If you choose to manually update the file please ensure that the log file already exists at the specified path and is readable by JIRA.
   7. For CVS Timeout, specify how many seconds it takes the CVS operation (e.g. rlog) to timeout
   8. The Password needs to be provided only if you let JIRA automatically retrieve the module's CVS log. Please specify the password that is needed to retrieve the log using the method specified in the CVS Root. If no password is required, leave the field empty.
   9. (Optional) For Base URL in the 'ViewCVS Details' section of the page, enter the fully qualified URL (i.e. include 'http://' or 'https://' at the beginning) to the ViewCVS site of the CVS module. The URL needs to point to the root of the module on the ViewCVS site.
      Note

      If you are integrating with FishEye you do not need to perform any special steps. FishEye can resolve all the URLs that ViewCVS expects. You just need to enter the fully qualified URL to your FishEye installation and the specific repository you wish to view. This is the same URL you would get if you were to browse to the project within FishEye.
   10. (Optional) For Root Parameter in the 'ViewCVS Details' section of the page, enter the name of the Project Root that is used in ViewCVS to navigate the CVS module. This parameter is required only if ViewCVS has been set up to work with multiple CVS modules, and this module is not the default module on the ViewCVS server. The value that should be placed in this field is the same as the value of the 'root' URL parameter that appears on every ViewCVS URL (e.g. when viewing a file). If the URL that appears in your browser when viewing a file from this CVS module on ViewCVS does not have the 'root' parameter, leave this field blank.
7. Click the 'Add' button.
8. This should bring you back to the 'CVS Modules' page, where you should see the new CVS module listed. You can edit and delete this module here.

1. Log in as a user with the 'JIRA Administrators' global permission.

2. Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard:

   

3. In the left-hand navigation panel, click the 'Projects' link.
4. This will bring up the 'Projects' page. It lists all the existing projects. Select a project that you would like to associate with the CVS module.
5. The project's summary page sill be displayed. Next to 'CVS Modules' click the 'Celect Module' link. This will display the 'Select Version Control Modules' page, where you can associate the project with a CVS module (or with multiple CVS modules, in JIRA Professional and Enterprise editions).
6. Select the appropriate module(s), and click the 'Select' button.

The 'View Version Control' permission needs to be given to users/groups/roles that should be allowed to see CVS commit information. Note: by default this permission is given to the 'jira-developers' group. Please read the Project Permissions section, and follow the instructions given there to assign the 'View Version Control' permission.

To disable automatic CVS log retrieval for a CVS module please choose the 'I would like to update the log myself' option for the module's 'Log Retrieval' attribute.

If you have disabled automatic CVS log retrieval for the CVS module, JIRA will only parse the CVS log periodically. Therefore, for the new commit information to appear in JIRA, the log needs to be updated by other means. This can either be done manually, or a scheduled CVS update script can be used.

To minimise the network traffic between JIRA and the CVS server, JIRA updates and re-parses the commit information of the associated CVS modules only once during the specified period of time. By default, this period of time is 1 hour, but it can be adjusted if required.

When the first CVS module is created in JIRA, a background service is automatically started. The service is called 'VCS Update Service'. To change the frequency of the module updates, follow these steps:

1. Log in as a user with the 'JIRA System Administrators' global permission.

2. Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard:

   

3. Open the 'System' tab of the left-hand menu, if it is not already open.
4. Select 'Services' from the 'System' tab. A page showing all the configured services will appear. If at least one CVS module has been configured, the 'VCS Update Service' should be present in the list.
5. Click the 'Edit' link in the right-most column of the 'VCS Update Service'. This will display a page where you can set the delay for the service.
6. Change the value as required. Remember that the delay is specified in minutes.
7. Click the 'Update' button to make the changes take effect.

Please keep in mind:

• The CVS modules are updated one after another every specified period of time. That is, it is not possible to specify a different update delay for each configured CVS module.
• If you are using automatic log retrieval for your CVS modules and you set the delay to a very low value, the bandwidth consumption between JIRA and the CVS server might be very high.
• If the delay is set to a very large value, the 'new' cvs commit messages will not appear in JIRA for some time.

JIRA does not currently support CVS aliases. If you have a CVS alias that references more than one module, please create each CVS module in JIRA and then associate each module with the relevant JIRA project(s) (assuming you are using JIRA Professional or Enterprise edition, as Standard edition only supports one CVS module per project). The feature request for adding CVS alias module support to JIRA is JRA-4586. Please vote for the issue to increase its popularity. Please refer to this document, which describes the way Atlassian implements new features and improvements.