SCMLoop - Connect External Repositories

Introduction

This document describes how to install the Codebeamer SCMLoop component. Codebeamer has built in support for so called Managed Repositories. Managed Repositories are SCM repositories created and maintained by Codebeamer itself so you do not have to read this document.

SCMLoop is a notification mechanism, which allows associating commits to a Source Code Management (SCM) repository with Work Items in Codebeamer.

Currently, SCMLoop is available for the following SCM systems:

• Git (only on Unix)
• Subversion
• Mercurial (Hg)
• Perforce

An exclusive feature of Managed (Git, Mercurial and Subversion) Repositories is the seamless integration to create and administrate (including access control) of repository with Codebeamer.

You only need to setup the extra SCMLoop component manually if you want to connect already existing (external) Subversion, Git, Mercurial to Codebeamer not running on Codebeamer server to for example associate SCM changesets (commits) to Codebeamer Work Items.

Installing SCMLoop

You need to install the SCMLoop component on every server that hosts SCM repositories you want to connect.

Unpack the SCMLoop distribution archive from CB/tomcat/webapps/cb/scmloop.zip to a publicly accessible directory/folder. Either on each server that hosts SCM repositories, or on a network folder that is accessible from each SCM host.

The JRE version is identical with the Codebeamer version where the SCMLoop distribution originates from.

In order for SCMLoop to work, its configuration must be adjusted to the current environment.

On Windows systems you have to edit the script scmloop/scmloop.bat, on Unix systems scmloop/scmloop, and modify the values of the following variables:

Make sure, that all SCM users are allowed to access and execute the scmloop[.bat] script. On Linux/Unix systems it must be ensured (for example: using command chmod) that the script scmloop is executable.

After you have successfully installed and configured SCMLoop, you can now start to instrument your SCM repositories.

Installation for Mercurial

Install Mercurial 1.8 or later (http://mercurial.selenic.com/wiki/Download) and add hg to the PATH. On Windows use: setx PATH “%PATH%;MERCURIAL_HOME”

on Linux use export PATH=$PATH:MERCURIAL_HOME

where MERCURIAL_HOME is the directory where you installed Mercurial.

Instrumenting SCM Repositories

Instrumenting a SCM repository means to add appropriate SCMLoop callbacks/hooks to every SCM repository you want to connect to Codebeamer (or configuration file for Mercurial).

The SCMLoop distribution contains pre-instrumented examples for all files named in this chapter.

When copying the example files, please take care to adjust the path to the scmloop directory accordingly.

Instrumenting a Git Repository

We assume that the repository already exists and is accessible. The templates of the Git hook scripts can be found under git/<operating_system> directory in scmloop.zip (where <operating_system> is either windows or unix).

1. Copy the files from git/<operating_system> to the hooks folder of the git repository.
2. Edit the scripts: replace the string ${scmloop}}} with the actual path of the scmloop script.
3. On Linux/Unix systems it must be ensured (eg. using command chmod) that the scripts are executable.
4. Create a file called codebeamer.properties under the .git directory of your repository or under the top directory in case of bare repository and add the following line to it: repositoryId= repository-ID

where repository-ID is the id of the Codebeamer repository that you want to associate the repository with.

Instrumenting a Subversion Repository

We assume that the repository already exists and is accessible. The templates of the Subversion hook scripts can be found under svn/<operating_system> directory in scmloop.zip (where <operating_system> is either windows or unix).

1. Check out the hooks directory of the Subversion repository to some working directory.
2. Copy the files from svn/<operating_system> to the hooks folder of the working directory.
3. Edit the scripts: replace the string ${scmloop}}} with the actual path of the scmloop script.
4. On Linux/Unix systems it must be ensured (eg. using command chmod) that the scripts are executable.

Create a file codebeamer.properties under conf in your repository and add the following line to it: repositoryId= repository-ID

where repository-ID is the id of the Codebeamer repository that you want to associate the repository with.

1. Commit your changes to the repository.

Instrumenting a Mercurial Repository

We assume that the repository already exists and is accessible. The mercurial example configuration files can be found under the hg directory in scmloop.zip.

1. Check hgrc file under .hg directory (hidden directory at the root of repository) of the Mercurial repository. If there is an already existing one, append content of the provided hgrc file to the original one (with a preferred editor), otherwise copy it to .hg dir.
2. Set your repositoryId property for the project where this repository used:
   [codebeamer]
   repositoryId = 266 # (number!)
   ...
3. Create a new file called hgrc-codebeamer,
4. Write this in the file:
   

   #DO NOT MODIFY THIS FILE UNLESS YOU KNOW WHAT YOU ARE DOING
   [web]
   allow_push = *
   allow_read = *
   [hooks]
   changegroup = "${hookDirectory}/changegroup-hook" hg_post_receive
   pretxnchangegroup = "${hookDirectory}/changegroup-hook" hg_pre_update
   [extensions]
   # enables the strip command
   mq =
   [ui]
   merge = internal:merge

5. In hgrc-codebeamer replace all occurrences of the string ${hookDirectory}}} with the absolute path of the directory where you copied the scripts to.
6. Copy the changegroup-hook(.bat) scripts from hg/<operating_system> (in scmloop.zip) to the .hg directory of the mercurial repository being served.
7. Replace the string ${scmloop}}} with the actual path of the scmloop script.
8. On Linux/Unix systems it must be ensured (eg. using command chmod) that the scripts are executable.
9. (Optional) In hgrc-codebeamer set your host name as it was registered in Codebeamer. This value will be the hostname of the machine where the Mercurial run by default.
   [codebeamer]
   host = myscmhost
   ...
10. (Optional) In hgrc-codebeamer set cburl property in the hgrc file according to the settings of your Codebeamer commit URL (this will be set to http://localhost:8080/cb/sccCommitInfo if missing):
    [codebeamer]
    cburl = http://mycbhost
    ...
11. (Optional) Check and set proxyhost, proxyport, proxyuser, password properties in the hgrc file according to the settings of your network like:
    [codebeamer]
    proxyhost = myproxy
    proxyport = 81
    proxyuser = myproxyuser
    password = v3ght # put password here in a base64 encoded form
    ...

Online tool can be used for base64 encoding

(like: http://www.motobit.com/util/base64-decoder-encoder.asp)

1. (Optional) If you would like to ignore Codebeamer accessibility errors, set the ignore flag (false by default):
   
   [codebeamer]
   ...
   ignore = true

Instrumenting a Perforce Repository

For more information about Perforce SCMLoop integration and installation procedure, see Using Perforce with codeBeamer.