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. Set managed repository URLs in 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
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
hg clone http://codebeamer.host:8000/repository.name
or
cd your.local.repository.dir
hg clone ssh://codebeamer@codebeamer.host/repository.name
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"
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"
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
nano hgrc
Alter the file's [ui] section to be like:
...
[[ui]
username = my.codebeamer.username <my.codebeamer@email.address>
...
[[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"
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
Login to Codebeamer and:
1. Select your Project from context menu.
2. 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.