Integrating JIRA with CVS and ViewCVS notes
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.
- 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:
On this page:
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.
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.
- 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.
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:
- 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.
- Log in as a user with the 'JIRA System Administrators' global permission.
- Choose > Add-ons. Select CVS Modules to open the CVS Modules page.
- Click on the 'Add new CVS module' link on this page.
- This will bring up the 'Add CVS Module' page.
Fill in as follows:
- For 'Name' put a short descriptive name, possibly just the name of the CVS module as it appears in your CVS repository.
- (Optional) For 'Description' put a short phrase that describes this CVS module.
- 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.
- 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 checkoutcommand.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.
- 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.
- 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.
- For 'CVS Timeout', specify how many seconds it takes the CVS operation (e.g. rlog) to timeout
- 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.
(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.
- (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.
- Click the 'Add' button.
- 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.
Step 2. Associate Project(s) with CVS Modules
- Log in as a user with the 'JIRA Administrators' global permission.
Error rendering macro 'excerpt-include' : No link could be created for 'Navigating to a Project Summary Page'.In this case, select the project you want to associated with the CVS modules.
- The project's summary page will be displayed. Next to 'CVS Modules', click the 'Change' 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).
- 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.
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:
- Log in as a user with the 'JIRA System Administrators' global permission.
Error rendering macro 'excerpt-include' : No link could be created for 'Navigating to the Services Administration Console'.If at least one CVS module has been configured, the 'VCS Update Service' should be present in the list.
- 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.
- Change the value as required. Remember that the delay is specified in minutes.
- 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).
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 Implementation of New Features Policy which describes the way Atlassian implements new features and improvements.
The minimum required CVS server version is 1.12.13 and there are actually two "forked" versions of CVS for Linux.
- Redhat/Fedora/SuSe based distributions use - Concurrent Versions System (CVS) 1.11.xx (client/server)
- Debian/Ubuntu based distributions use - Concurrent Versions System (CVS) 1.12.xx (client/server)
Upgrading of CVS won't help Redhat users because they have gone down a different fork and provide upgrades only for that fork. Each fork has different command line switches. The solution is to download the source code for CVS 11.12.xx (the one Debian/Ubuntu uses) & compile from source.
The source from http://ftp.gnu.org/non-gnu/cvs/binary/ . There are two directories:
- Feature directory - contains debian/ubuntu version 11.12.xx.
- Stable - contains the redhat version 11.11.xx.
Sample set of commands that can be used to to install the source from the web cvs-11.12.13.tar.bz2
- If cvs-1.11.xx is already installed on the box this will safely override it. It appears that even if both versions are on the one box and they work just fine.
- Trying to to remove the old CVS from Redhat will result in the package manager wanting to remove Tomcat as a dependency, which may be right depending on the way JIRA is deployed. So this also means that the above steps have to be repeated every time the package manager updates CVS with cvs-1.11.xx and to override it with cvs-1.12.xx .
- The best option may be is not to install the Redhat CVS at all and just compile from source.
Was this helpful?
Thanks for your feedback!