Using Mercurial with CodeBeamer

Tags: Mercurial Version Control System

Using Mercurial with CodeBeamer

Mercurial Overview

Mercurial is a fast, lightweight Source Control Management system designed for efficient handling of very large distributed projects. It is also called hg for short.

CodeBeamer has out-of-the-box support for mercurial repository access, for both 'external' or 'managed' repository configurations.

Installing codeBeamer with Mercurial

In the codeBeamer Windows versions, codeBeamer is shipped with Mercurial and no installation is necessary unless access via Apache is required.

Download Mercurial from http://www.selenic.com/mercurial/wiki/index.cgi/BinaryPackagesor use the mercurial Linux package. On Windows we recommend using one of the EXE installers because we experienced some problems when using the MSI ones.
Install Mercurial (this is done by the package manager on Linux). See Mercurial wiki for help.
Install codeBeamer
Start codeBeamer

At this point codeBeamer and Mercurial should be working together and you should be able to create codeBeamer projects with a managed Mercurial repository. The whole process takes about 10-15 minutes.

There is no managed ACL (Access Control List) support for directories in codeBeamer for Mercurial, so authenticated users can access any content under a repository. If necessary, one can maintain ACL by the built-in ACL extension of Mercurial.

The Mercurial server component in codeBeamer is called hgserve (supports only cloning) and it is started and stopped automatically by codeBeamer.

Mercurial Client on Windows

On a Windows platform additional setup is necessary to use Mercurial over SSH.

First generate an SSH keypair as described in Setting Up SSH Authentication for Git and Mercurial

Modify the Mercurial setup to use your ssh client command in global configuration (mercurial.ini under your home):

[ui]
...
ssh = "C:\Program Files\TortoiseHg\TortoisePlink.exe" -ssh -2 -i "C:\Documents and Settings\adam.berkes\key.ppk"
...

There are certain versions of putty which fail to communicate this way, so we advise using the plink program from TortoiseHg

. If you do this don't forget to modify Mercurial.ini in the installation directory of TortoiseHg (by default C:\Program Files\TortoiseHg\Mercurial.ini) as well.

Using Mercurial in the Eclipse IDE with the MercurialEclipse plugin

MercurialEclipse is the most commonly used IDE integration plugin. Using it for development with codeBeamer Managed Mercurial Repositories is easy. For download information visit MercurialEclipse download.
Learn more about using Mercurial with codeBeamer under Eclipse IDE in this page.

URLs of Managed Mercurial Repositories

Mercurial can be configured three ways in connection with codeBeamer:

Hg own sharing (serve)
Apache http/https access
Ssh access to commit changes and public read access
Mix of the previous two approaches

If hg serve is turned off in codeBeamer's configuration (i.e. general.xml, see Sharing Managed Repositories) the Apache server can be setup according to Configuring Apache for Mercurial. In this case only members with SCM_VIEW permission can read (clone/pull) project repository and only members with SCM_COMMIT permission can write into it (push). CodeBeamer maintains repository access configuration information however additional restrictions can be applied in Apache configuration if necessary. For example:

http://javaforge.com/hg/hgeclipse

If Apache is not configured but hg serve is started by the codeBeamer server and OpenSSH is installed on the server then all users have public read access to the repository (default port: 8000) but only users with SCM_COMMIT permission have write access to it (e.g. push). System Administrators can also run remote hg commands. OpenSSH is officially supported only on Linux platforms however it can be set up using Cygwin on Windows. Examples:

Repository read access example: http://localhost:8000/myrepositoryname
Repository read-write access example: https://javaforge.com/hg/hgeclipse
Repository read-write access example: ssh://codebeamer@javaforge.com/hgeclipse

The above scenarios can be mixed if both Apache and OpenSSH are configured. Authors can send their changes through SSH or HTTPS, while HTTP access is restricted to only certain members.

How to Use Mercurial with codeBeamer

Setting Up SSH User Authentication (Step 1)

Before you can work in codeBeamer with Managed Mercurial Repository it needs to know who you are and you need an OpenSSH key (keypair). This consists of a private and a public key, and you must provide your public key to codeBeamer to allow security control of mercurial communication over ssh. Keep your private key in a safe place; this will probably be the place where it was created.

To generate the keys please follow the steps described in Setting Up SSH Authentication for Git and Mercurial.

Creating and Joining Projects with Managed Mercurial Repositories (Step 2)

Project repositories subtend a base URL which is set up by the codeBeamer System Administrator. This access URL must be properly configured first, before your managed repository is configured. See

Administrator's Guide or your codeBeamer System Administrator for more help.

Follow the steps described in Creating Managed Repositories.

Cloning Repositories, Committing and Pushing Changes (Step 3)

We now need to get our copy of the source code so we can work on it.

On your desktop machine open a terminal window and enter the following commands:

In Apache (scenario 1):

cd your.local.repository.dir
hg clone http://cb.username@codebeamer.host/hg/repository.name

Note: you will be asked for your codeBeamer password for authentication.

In public access/ssh (scenario 2):

cd your.local.repository.dir
hg clone http://codebeamer.host:8000/repository.name

cd your.local.repository.dir
hg clone ssh://codebeamer@codebeamer.host/repository.name

Edit the files, fix bugs, etc. Now commit your changes to the repository. In the following instructions only the apache (http access) scenario will be used - others will differ only in the url used in the commands (see above).

On your desktop machine open a terminal window and enter the following commands: If you added/removed any local file:

cd your.local.repository.dir
hg addremove
hg commit -m "Commit message" -u "my.codebeamer.username"

otherwise

cd your.local.repository.dir
hg commit -m "Commit message" -u "my.codebeamer.username"

This will commit changes locally to your repository. Now send your changes to codeBeamer:

hg push http://cb.username@codebeamer.host/hg/repository.name

Note: if you are using a 1-to-1 repository clone, simply using hg push without parameters works.

To use shorter commands, the author's identity can be defined by editing the hgrc file of the repository:

cd your.local.repository.dir/.hg
nano hgrc

Alter the file's [ui] section to be like:

...
[[ui]
username = my.codebeamer.username <my.codebeamer@email.address>
...

This will set your identity and commits can be sent by 'hg commit -m "..."' More than 1 commit can be sent to codeBeamer with a single push operation. Simply make your changes and repeat the steps above without the push. When you want to share your work execute a 'hg pull -u' to get latest revisions and update (or merge) your local clone, and then execute 'hg push'. That will send all your changes at once.

Associating Issues with Commits (Step 4)

To associate an issue with a commit first create an issue within a codeBeamer tracker. Keep in mind the id of the generated issue, and start to work the source code implement or fix in connection with it. When done open a terminal window and enter the following commands (replace "1234" with the ID of the issue you want to associate your commit with):

cd your.local.repository.dir
hg commit -m "#1234 Commit message" -u "my.codebeamer.username"

Use the issue ID you've created: this will commit changes locally to your repository. Now send your changes to codeBeamer (replace "<codebeamer.host>" with your actual server name or server IP address):

hg push http://cb.username@<codebeamer.host>/hg/repository.name

Select your Project from context menu
Click on the SCM Repository tool menu

You can now see your commit(s) at the top of the history, and the issue #1234 (check the link on the rightmost cell) is associated with your change. You can check the "back" association by clicking on this issue link, and see your change info on SCM Commits tab at the bottom of the issue.

For more information on associating issues with commits, please see Tracing Source Code Changes to Requirements, Task and Bugs