Mercurial

Configuring a Mercurial Source Repository

The instructions in this section apply to configuring a source repository for both Plans and Jobs.

To configure a Mercurial source repository:
If you are creating a new Plan or new Job, or have come from the Editing a Plan or Editing a Job topics, start at step 4.

1. Navigate to the source repository settings for a Plan or Job, as described on Specifying the Source Repository for a Plan and Specifying the Source Repository for a Job respectively.
   
2. Mercurial configuration
   • 'Use Plan's Repository' (Only available when configuring a Job) — Select this option if you wish to use the 'default source repository' of the Plan to which your Job belongs. If you select this option, you do not need to configure any further source repository options below, although if you are creating a new Job, continue with the Builder Configuration section of Creating a New Job.
   • 'Repository' — select 'Mercurial'.
   • 'Repository URL' — Type the full path to your Mercurial repository (e.g. 'http://bitbucket.org/sinbad/ogre'). Valid URLs are of the form:
     • local/filesystem/path[#revision]
     • file://local/filesystem/path[#revision]
     • http://[user[:pass]@]host[:port]/[path][#revision]
     • https://[user[:pass]@]host[:port]/[path][#revision]
     • ssh://[user[:pass]@]host[:port]/[path][#revision]
       (for further references visit Mercurial documentation)
   • 'Branch' (Optional) — Type the name of the relevant branch you want to work on. Leave empty to work on default branch.
   • 'Username' (Optional) — Type the username (if any) required to access the repository.
   • 'Authentication Type' — Select the authentication type you want to access Mercurial repository;
     • If you select 'Password' (use that authentication type for http/https hosted repositories), the following fields will appear:
       • 'Password' (Optional) — Type the password you want to access the repository.
       • 'Change Password' (Only available after first saving the Plan/Job with a password) — Select this check box if you want to change the password that is used to access the repository.
     • If you select 'Keyfile with passphrase' (use that authentication type for repositories accessible through ssh), the following fields will appear:
       • 'SSH Key' — Choose an SSH private key from your hard drive.
       • 'Change SSH Key' (Only available after first saving the Plan/Job with an SSH private key) — Select this check box if you want to change your SSH private key.
       • 'Passphrase' — Type the passphrase for your SSH private key.
       • 'Change Passphrase' (Only available after first saving the Plan/Job with a passphrase) — Select this check box if you want to change the passphrase for your SSH private key.
     • If you select 'Keyfile without passphrase' (this authentication type is similar to above except it is a bit faster), the following fields will appear:
       • 'SSH Key' — Choose an SSH private key from your hard drive.
       • 'Change SSH Key' (Only available after first saving the Plan/Job with an SSH private key) — Select this check box if you want to change your SSH private key.
     • If you select 'Default Mercurial credentials', Bamboo will rely on default hg authentication. Use this option, for example, if you had set up the Bamboo server manually with SSH servers defined in .ssh/config, valid SSH identity files, etc.
   • 'Command timeout' (Optional) — Type the number of minutes bamboo should wait for hg commands to finish. This is useful to cut hung Mercurial processes. On the slower networks you may consider increasing default timeout to allow bamboo making initial clone of mercurial repository.
   • 'Location of POM file' (Only available when importing a Maven 2 project) — Type the path to your project's pom.xml file which is relative to the root of your Mercurial Repository URL (defined above).
   • 'Delay changeset detection' — Select this setting to allow Bamboo postponing collecting code changes after build phase. Otherwise Bamboo server needs to do full clone of repository before triggering the build, which may take time especially if it is the first build. Consider using this option if your build agents have significantly faster connection to the repository than Bamboo server.
   • 'Clean cache directory' — Internally, Bamboo shares similar repositories between Plans/Jobs. It caches them in a special directory. Select this setting to force Bamboo removing cache directory for that plan before any occurrence of code change detection or plan build. Turning this option on will greatly increase the time it takes to complete a build (or even change detection). Consider using this option for example when remote repository was replaced but is still accessible through the same url as the previous one.
   • 'Verbose logs' — Turns on --verbose and --debug options in hg commands and pass the output to build logs. Use that option if you encounter problems in Bamboo Mercurial behaviour.
3. Are you creating/cloning a new Plan or a new Job?

   • If you are creating a new Plan, continue with the Build Strategy section of Creating a New Plan.
   • If you are creating a new Job, continue with the Builder Configuration section of Creating a New Job.
   • If you are cloning an existing Plan or Job, continue on with the next step.
   • If you are importing a Maven 2 project, perform the Web Repository section of the Common Repository Configuration step below, before returning to the Enable this Plan section of Import a Maven 2 Project.

4. Common Repository Configuration (Only available when configuring an existing Plan/Job)

   • 'Force Clean Build:' (Optional) — You can force Bamboo to remove the source directory and check it out again prior to the Plan/Job build being built by selecting this option. Please note that this will greatly increase the time it takes to complete a build.
   • 'Clean working directory after each build:' (Optional) — You can force Bamboo to remove the source directory after the Plan/Job is completed building by selecting this option. Please note that this may increase build times but saves on disk space.
   • 'Include/Exclude Files:' (Only available when configuring a Plan) — You can specify a particular inclusion or exclusion pattern for file changes to be detected. If you select an option other than 'None', the following field will appear:
     • 'File Pattern:' — The regular expression for file changes which you wish to include/exclude.
   • 'Web Repository:' — Select the type of web repository ('None', 'Generic Web Repository', 'Mercurial Web Repository', 'FishEye') to be associated with this build. You will be able to view code changes related to your build via the build results.
     Only a subset of Web Repository options are available for your chosen repository type.
     • If 'Generic Web Repository' is selected:
       • 'Web Repository URL' — If your source repository can be accessed via a web browser, you can specify the URL of the source repository here. If you specify a Web Repository URL, then links to relevant files will be displayed in the 'Code Changes' section of a build result.
       • 'Web Repository Module' — The repository name of the Plan/Job, if the above Web Repository URL points to multiple repositories.
     • If 'Mercurial Web Repository' is selected:
       • 'Mercurial Web Repository Viewer Scheme' — Choose between using the BitBucket Web Repository Scheme (if you use BitBucket) or Mercurial's own default web server (Default Web Repository Scheme (hgserve)).
     • If 'FishEye' is selected:
       • 'FishEye URL' — The URL of your FishEye repository (e.g. 'https://atlaseye.atlassian.com/').
       • 'Repository Name' — The name of your FishEye repository (e.g. 'Bamboo'). This is effectively the alias for your repository path.
       • 'Repository Path' — The path for your FishEye repository (e.g. '/atlassian/bamboo/').

         How do I determine my Repository Path?

         If you have previously run builds with changes from your repository, the easiest way of determining your repository path is to view the code changes and copy the path from the start of the path of one of the changed files, up to (but not including) the appropriate root directory. The root directories for repositories are the ones shown by FishEye when browsing a repository (e.g. trunk)). For example, if a code change listed /atlassian/bamboo/trunk/bamboo-acceptance-test/pom.xml, the path would be /atlassian/bamboo/.
         If you have not previously run builds with changes from your repository, you will need to ask your FishEye administrator for the repository path indexed by FishEye.

   • 'Build Strategy' (Only available when configuring a Plan) — Choose one of the build strategy options (listed below), which will be used for triggering the execution of this Plan. You can change the Build Strategy at a later point in time as required.
     You may need to configure other options specific to your chosen build strategy.
     If you select Manual & dependent builds only when creating a new Plan, an initial build will not automatically be run. You can force an initial build to be executed automatically by adding the fire.initial.build.for.manual.strategy to your bamboo.cfg.xml file as described in Configuring System Properties.
5. Click the 'Save' button to save your changes.

Screenshot above: Source Repository — Mercurial

Appendix - Build Strategies

Notes

• If you wish to build plans on your server and remote agents using a Mercurial repository, you need to specify the location of the Mercurial hg client application for your Bamboo server and for each remote agent using Mercurial. These locations are set by specifying:
  • a mandatory local server Mercurial capability for your Bamboo server and
  • agent-specific remote Mercurial capabilities for each of your remote agents using Mercurial.
  You will not be able to create Plans/Jobs that use a Mercurial repository without specifying the shared local Mercurial capability first. Read more about configuring a Mercurial capability.

Related Topics

Specifying the Source Repository for a Plan
Specifying the Source Repository for a Job