Documentation for JIRA 4.0. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata

JIRA's CVS integration shows the related CVS commit information for an issue. When a CVS commit message mentions an issue, JIRA picks this up and displays the commit log in a tab in the mentioned issue.

JIRA's CVS integration features include:

  • Ability to interact with a CVS server log directly via local access, pserver or external (ssh) protocols, or to parse a CVS log file generated by an external process.
  • Access to the version control information in JIRA can be easily controlled using flexible permissions. If you are running a public instance of JIRA, and do not want the rest of the world to see the version control information, JIRA can be configured to restrict access to that information to the chosen users.
  • ViewCVS or FishEye are supported out-of-the-box; and Subversion is available as a plugin (drop-in extensions to JIRA).
  • If CVS integration is configured, the files and revisions in JIRA are linked to the relevant pages. E.g. the following screenshot shows a JIRA project:

    Because ViewCVS is configured, JIRA has turned the displayed commit information into ViewCVS links.
    • Clicking the name of the file will take the user to the ViewCVS file summary page.
    • Clicking the revision will take the user to the page that shows the contents of the file as it was at that revision.
    • Clicking the 'diff' summary will show the ViewCVS 'diff' page between the shown revision of the file and its previous revision.
  • Each project in JIRA can be associated with a CVS module. A project can also have multiple modules.

There are 3 steps to configure CVS integration in JIRA:

  1. Create a CVS module
  2. Associate project(s) with CVS module(s)
  3. Grant permission to view CVS information

How JIRA's CVS integration works

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.

Icon

Even if you are using local repository access JIRA will obtain the CVS log for the module and then parse it. JIRA does not access the CVS repository directly.

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 JIRADOC: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 JIRADOC:adjusting the frequency (see below) or JIRADOC: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.

Step 1. Create a CVS Module in JIRA

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.
    1. 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.
    2. 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 JIRADOC: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 JIRADOC:periodically just parse it. If you choose this option you will need to JIRADOC:update the CVS log by other means (e.g. manually or using a scheduled JIRADOC:script ) to keep the CVS information in JIRA current.
    3. 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 JIRADOC: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.
    4. For 'CVS Timeout', specify how many seconds it takes the CVS operation (e.g. rlog) to timeout
    5. 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.
    6. (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.
      Icon

      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.

    7. (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.
Icon

If JIRA has trouble understanding your local CVS Root (e.g. on Windows systems) please prefix the path with :local:. For example, :local:d:\some\path

Step 2. Associate Project(s) with CVS Modules

  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).
  6. Select the appropriate module(s), and click the 'Select' button.

Step 3. Configuring Permissions

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.

Disabling Automatic CVS Log Retrieval

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.

Icon

Before updating the module's CVS log, please check for the existence of a lock file with name 'cvslog.write.lock' in the same directory as the CVS log file. If the lock file exists, please wait until it is removed before updating the log.

When updating the CVS log for a module, please create a lock file with the name cvslog.write.lock in the same directory as the CVS log file to ensure that JIRA does not start parsing the log while it is still being updated. Please do not forget to remove the lock file after the update has finished.

Adjusting the Frequency of Module Updates

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.

CVS Aliases

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).

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.