Mercurial Integration  

Mercurial is a distributed version control system written in Python. This page covers complete steps for integrating a Mercurial repository with The Bug Gennie. The integration will encompass the following features:

• associate commits with issues based on commit message
• links towards Mercurial repository web browser
• transition issues through workflows based on commit message

Enabling the Module  

Prior to configuring the integration with Mercurial, it's necessary to enable the module:

1. Open the administration web page of The Bug Genie.
2. Select the Module settings option.
3. Switch to the Install new modules tab.
4. From the drop-down list select the VCS Integration module.
5. Click on the Install button and wait for the installation to finish.

The VCS integration can now be configured in projects.

Configuring Mercurial VCS Integration for a Project  

VCS integration is configured for each project individually:

1. Open the administration web page for a project in The Bug Genie.
2. Select the VCS Integration option.
3. Write down the project's ID number that is listed at the top of the page. This information is required later on when configuring the actual Mercurial hook in repository.
4. Set the Enable VCS Integration option to Enable for commits applying to existing issues only.
5. OPTIONAL: Set the Enable workflow? option to Enable for this project. This will allow you to automatically resolve/close issues with commit messages.
6. Configure access method. There are two possible methods - direct access (via shell), or access through TBG's web interface. Select in below steps the step you prefer.
1. Direct Access
1. Set the Access method option to Direct Access (via a tbg_cli).
2. HTTP Access (via a call to a URL)
1. Set the Access method option to HTTP Access.
2. Set the HTTP Passkey option to desired password by which the access will be protected. This password should be as strong as possible. It will be used only from within automatic hook calls, and therefore doesn't have to be re-typed over and over again.
7. Set the URL to repository browser option to full base URL where the repository can be found.
8. Configure the repository browser URLs. You can either select one of the predefined schemes (which will fill in this information automatically), or define your own scheme if none of the listed items match your repository browser.
1. hgweb
1. Set the Repository browser type option to hgweb.
9. Click on the Save button to apply your configuration changes.

The project is now fully configured on The Bug Genie side to process Mercurial repository commits.

Configuring Mercurial Repository for VCS Integration  

In addition to configuring the project, it's also necessary to set-up Mercurial hooks that will automatically push the information about new commits in a repository to The Bug Genie instance.

1. Download the Mercurial hook for The Bug Genie from VCSMercurial.
2. Place the hook script into location /usr/local/bin/thebuggenie_hg.py.
3. Set-up the permissions for the script:

 sudo chown root.root /usr/local/bin/thebuggenie_hg.py
 sudo chmod 755 /usr/local/bin/thebuggenie_hg.py

1. Edit the repository's hgrc configuration file. For example, if the repository resides in directory /var/lib/hg/example/, it is required to modify the configuration file /var/lib/hg/example/.hg/hgrc.
1. If the project was configured to use HTTP Access as Access method, add the following lines:

 [extensions]
 buggenie = /usr/local/bin/thebuggenie_hg.py
 
 [buggenie]
 method = http
 script = TBG_BASE_URL/vcs_integration/report
 passkey = PASSWORD
 project = PROJECT_NUMBER
 
 [hooks]
 changegroup.buggenie = python:buggenie.hook

1. The TBG_BASE_URL should be replaced with the base URL for The Bug Genie (i.e. the URL used to access the main index page The Bug Genie installation). For example: http://tbg.example.com/ or https://tbg.example.com/ (if using SSL).
2. The PASSWORD should be replaced with the same password as used for the HTTP Passkey option in the project configuration.
3. The PROJECT_NUMBER should be replaced by the same project ID number that was visible on the VCS Integration project configuration page.
1. If the project was configured to use Direct Access as Access method, add the following lines: @TODO: Write me

The Bug Genie and Mercurial repository should be fully integrated now. It is recommended to verify the integration by creating a single test issue in the project, and making a commit for it.