Mercurial Plugin

Skip to end of metadata
Go to start of metadata

This plugin integrates the Mercurial version control system with Jenkins.

Plugin Information

Plugin ID mercurial Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
1.50
Feb 28, 2014
1.509.4
multiple-scms (version:0.2, optional)
scm-api (version:0.1)
ssh-credentials (version:1.6)
credentials (version:1.9.4)
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
Jesse Glick (id: jglick)
Mirko Friedenhagen (id: mfriedenhagen)
Kohsuke Kawaguchi (id: kohsuke)
David M. Carr (id: davidmc24)
Willem Verstraeten (id: willemv)
Usage Installations 2013-Apr 3714
2013-May 3730
2013-Jun 3765
2013-Jul 3944
2013-Aug 3911
2013-Sep 3991
2013-Oct 4174
2013-Nov 4044
2013-Dec 3900
2014-Jan 4085
2014-Feb 4162
2014-Mar 4344

With this plugin, you can designate a Mercurial repository as the "upstream" repository. Every build will then run something like hg pull -u to bring the tip of this upstream repository. In a similar manner, polling will check if the upstream repository contains any new changes, and use that as the triggering condition of the new build.  This plugin is currently intended to support Mercurial 1.0 and later.

Viewers included are bitbucket, fisheye, google-code, hgweb, kiln, and rhodecode.

Push Notifications

As of version 1.38 it's possible to trigger builds using push notifications instead of polling. In your repository's .hg/hgrc file add:

[hooks]
commit.jenkins = wget -q -O /dev/null <jenkins root>/mercurial/notifyCommit?url=<repository remote url>
incoming.jenkins = wget -q -O /dev/null <jenkins root>/mercurial/notifyCommit?url=<repository remote url>

This will scan all the jobs that's configured to check out the specified URL, and if they are also configured with polling, it'll immediately trigger the polling (and if that finds a change worth a build, a build will be triggered in turn.)

This allows a script to remain the same when jobs come and go in Jenkins. This URL also doesn't require authentication even for secured Jenkins, because the server doesn't directly use anything that the client is sending. It runs polling to verify that there is a change, before it actually starts a build.

When successful, this will return the list of projects that it triggered polling as a response.

Jobs on Jenkins need to be configured with the SCM polling option to benefit from this behavior. This is so that you can have some jobs that are never triggered by the post-commit hook, such as release related tasks, by omitting the SCM polling option.

Windows/TortoiseHG Integration 

There are some caveats to running TortoiseHG on windows, particularly with ssh. Here are some notes to help.

Prerequisites:

  • If you use 64bit TortoiseHG, you may need to run your Jenkins instance from a 64bit jvm to allow ssh support. If not, the initial clone will hang.
  • For ssh support, you will either  need putty/pageant installed to send the proper keys to the server if the keys are password protected, or you will need to specify the change in the ui section mercurial.ini found in C:\Users\username\mercurial.ini to use a specific key:
    [ui]
    ssh="C:\program files\tortoisehg\TortoisePlink.exe" -i "C:\Users\username\key_nopass.ppk"
    
  • To accept the host key, use plink or putty to connect to the server manually and accept the key prior to the initial clone. You can also use the tortoiseplink.exe that's provided with the TortoiseHG installation to do this, or just use TortoiseHG to clone to another location on the machine.
  • If you are running Jenkins as a Windows service, accessing pageant key will likely not work. In this case, use a key without passphrase configured in mercurial.ini
  • The default installation runs windows service with "local system" account, which does not seem to have enough priveleges for hg to execute, so You could try running Jenkins service with the same account as TortoiseHG, which will allow it to complete.

Example, from a command prompt: 

"C:\program files\tortoisehg\TortoisePlink.exe" user@hg.example.com

Click 'Yes' on the host key dialog. You can then cancel the next dialog prompting for password.

Main Configuration, Step by Step:

  1. Install the Jenkins Mercurial Plugin.
  2. Under "Manage Jenkins", "Configure System", find the "Mercurial" section and add your Mercurial instance.

3. Save the configuration.

Job Configuration

  1.  Select Mercurial under Source Code Management
  2.  Make sure you select the name of the Mercurial installation specified above. In my case, "TortoiseHG"
  3.  The url can either be ssh or https.

Example SSH URL:

ssh://hg@bitbucket.org/myuser/projectname

Other Windows+TortoiseHG+ssh notes:

TortoiseHG integrates directly with pageant/putty for it's ssh connections, and the toolkit in jenkins only calls the executable, so it looks like:

Jenkins -> Mercurial Plugin -> TortoiseHG > plink/pageant

Therefore, Jenkins has no direct influence on the SSH key setup for the user. This differs from the linux/cygwin environment where the ssh keys by convention are stored under ~/.ssh. 

Environment Variables

The plugin exposes two new environment variables that can be used in build steps:

  • MERCURIAL_REVISION: the changeset ID (SHA-1 hash) that uniquely identifies the changeset being built
  • MERCURIAL_REVISION_NUMBER: the revision number for the changeset being built. since this number may be different in each clone of a repository, it is generally better to use MERCURIAL_REVISION.

Auto Installation

The plugin supports generic tool auto-installation methods for your Mercurial installation, though it does not publish a catalog of Mercurial versions. For users of Linux machines (with Python preinstalled), you can use ArchLinux packages. For example, in /configure under Mercurial installations, add a Mercurial installation with whatever Name you like, Executable = INSTALLATION/bin/hg, Install automatically, Run Command, Label = linux (if desired to limit this to slaves configured with the same label), Command = [ -d usr ] || wget -q -O - http://www.archlinux.org/packages/extra/i686/mercurial/download/ | xzcat | tar xvf - (or …/x86_64/… for 64-bit slaves), Tool Home = usr, and configure a job with this installation tied to a Linux slave.

Changelog

Version 1.50 (Feb 28, 2014)

All changes in beta 1 & 2 plus:

Version 1.50 beta 2 (Feb 19, 2014) (experimental update center only)

  • (pull #49) Added branch column header.
  • issue #15829 Do not do a fresh clone for every build when using repository sharing on a slave.
  • issue #16654 Option to disable changelog calculation, which can be expensive in some cases.
  • issue #18237 Fix use of Multiple SCMs plugin with matrix builds.
  • issue #5723 Permit arbitrary configuration options to be set on a Mercurial installation.

Version 1.50 beta 1 (Jan 08, 2014) (experimental update center only)

  • 1.509.4 baseline.
  • Require credentials 1.9.4 for an important bugfix.
  • (pull #47) New extension point for overriding polling comparisons.
  • issue #5396 Supported option to update to a tag rather than a branch.
  • issue #5452 Properly escape user names in changelog.
  • (pull #48) Added SSH private key credentials support. (Still no SSL client certificate support.)

Version 1.49 (Oct 22, 2013)

  • issue #20186 Jenkins 1.536+ would throw errors when saving jobs with a Mercurial browser set; fixing plugin to not use unnecessary code.

Version 1.48 (Oct 08, 2013)

  • Same as 1.48 beta 1 except tested against a 1.509.3 baseline.

Version 1.48 beta 1 (Sep 20, 2013) (experimental update center only)

  • Improved Credentials integration by using different command-line options that should work with the largefiles extension and otherwise be more reliable.
  • Added integration with the SCM API Plugin.

Version 1.47 (Sep 10, 2013)

  • issue #19493 Use form validation to alert users of invalid repository browser URLs before saving.
  • issue #7351 Add support for HTTP(S) username/password credentials. (Not yet implemented: SSL client certificates, SSH private keys.)
  • issue #18807 Ignore SCM triggers which ask to suppress post-commit hooks. (Plugin now requires 1.509.2 or newer.)
  • issue #18252 Added ability to recognize /var/hg/stuff in push polling. Previously, it caused an error because of the lack of a URL protocol.
  • (pull #42) Added MERCURIAL_REVISION_SHORT environment variable.

Version 1.46 (May 14, 2013)

  • issue #9686 Expand default values of string parameters when polling.

Version 1.45 (April 21, 2013)

  • issue #3907 Let all runs in a matrix build update to the same Mercurial revision.
  • issue #13669 Replaced NullPointerException with a more informative IOException caching fails during polling.
  • issue #17353 Assume UTF-8 encoding for metadata in changelog.xml
  • don't relink when sharing repositories, as that makes mercurial time out.

Version 1.44 (Feb 26, 2013)

  • (pull #33) Ignore authentication section in URL for purposes of matching push notifications.

Version 1.43 (Feb 05, 2013)

  • (pull #32) Fix push notification when anonymous users lack read access.

Version 1.42 (Nov 06, 2012)

  • issue #12763 Excessive lock contention when using mercurial cache with multiple repos and slaves.

Version 1.41 (Jun 05, 2012)

  • issue #13174 (continued) Do not ignore .hgsubstate changes when polling.

Version 1.40 (May 22, 2012)

Version 1.39 (Apr 27, 2012)

  • issue #11976 NonExistentFieldException warnings after upgrading mercurial plugin to 1.38
  • issue #11877 Jenkins fails to run "hg" command even though the path to it is specified correctly
  • issue #2252 Mention SCM changeset ID in email
  • issue #7594 Merges across named branches should not be ignored.
  • issue #11809 Time out on pull operations.
  • Restore 'hg relink' usage accidentally removed earlier.
  • issue #12162 Pay attention to subdirectory, needed for use in Multi-SCM Plugin (recommended replacement for Forest).
  • issue #12361 Directory separator '/' for modules supported on Windows.
  • issue #12404 Enable polling without a workspace when using caches.

Version 1.38 (Dec 2, 2011)

  • issue #11360 Add support for RhodeCode as a Mercurial Repository Browser (patches by marc-guenther and marcsanfacon).
  • issue #10255 Mercurial Changelog should compare with previous build (patches by willemv and davidmc24).
  • issue #11363 Add support for Mercurial's ShareExtension to reduce disk usage (patches by willemv).
  • Dropping support for the Forest extension.
  • issue #11460 "Repository URL" field in mercurial plugin should trim input.
  • Added push notification mechanism.

Version 1.37 (Jun 13 2011)

  • issue #9964 Expose the node name via the API and the GUI.
  • issue #7878 MercurialSCM.update(...) should respect slave node default encoding.

Version 1.35 (Jan 19 2011)

  • issue #7723 Attempted fix for problem calculating changeset ID of workspace.

Version 1.34 (Nov 15 2010)

Version 1.33 (Aug 13 2010)

Version 1.32 (Aug 12 2010)

  • issue #3602 Ability to specify a subdirectory of the workspace for the Mercurial repository.
  • issue #6548 NPE when cache was out of commission.

Version 1.31 (Jun 10 2010)

  • issue #6337 Polling broken when module list specified.

Version 1.30 (May 17 2010)

  • issue #6549 Mercurial caches for slaves was broken in 1.29.

Version 1.29 (May 12 2010)

  • issue #6517 Reduce memory consumption representing merges in large repositories.

Version 1.28 (Mar 29 2010)

  • issue #5835 Include repository browsing support for Kiln (patch by timmytonyboots).

Version 1.27 (Mar 19 2010)

  • issue #4794 Option to maintain local caches of Mercurial repositories.

Version 1.26 (Mar 09 2010)

  • issue #4271 Support parameter expansion for branch (or tag) field.
  • issue #2180 Polling period can be set shorter than the quiet period now.

Version 1.25 (Nov 30 2009)

  • issue #4672 Option to run Mercurial with --debug.
  • Dropping support for Mercurial 0.9.x. Use 1.0 at least.
  • issue #4972 Do not consider merge changesets for purposes of polling.
  • issue #4846 Option to download Forest extension on demand. Useful for hard-to-administer slaves.
  • Restoring ability to specify Mercurial executable name other than INSTALLATION/bin/hg (lost in 1.17 with move to tool installation system).
  • issue #1099 Make "modules" list work even after restart.

Version 1.24 (Nov 13 2009)

Version 1.23 (Oct 23 2009)

  • Module list should filter the changelog as well as polling. (issue #4702)
  • Implement getAffectedFiles in MercurialChangeSet r22903.

Version 1.22 (Sep 23 2009)

Version 1.21 (Sep 22 2009)

Version 1.20 (Sep 21 2009)

  • issue #4514 alternate browsers do not show up in dropdown after updating the plugin. This is an intermediate
    quick fix until version 1.325 of the core is released.

Version 1.19 (Sep 20 2009)

  • issue #4461 fix was leaking threads.
  • Mercurial changelog now links to diffs and specific revisions of files (issue #4493)

Version 1.18 (Sep 18 2009)

  • 1.17 release was botched (Maven issue), rereleasing as 1.18.

Version 1.17 (Sep 18 2009)

  • Fixed various issues with named branches. (issue #4281)
  • If switching to clone due to path mismatch, at least explain what is happening in the build log. (issue #1420)
  • Kill Hg polling process after one hour, assuming it is stuck on a bad network connection. (issue #4461)
  • Multiple Mercurial installations may now be configured as tools. See Tool Auto-Installation for background.
  • Environment variable "MERCURIAL_REVISION" that contains the node ID like "272a7f93d92d..." is now exposed to builds. (Also retain ID of tip revision for each build; not yet exposed via XML API or GUI but could be useful later.)
  • Google Code and BitKeeper can be now specified (in addition to hgweb) as a repository browser (issue #4426)

Version 1.16 (May 27 2009)

  • The plugin was failing to clean up tmp*style file if the check out failed. (issue #3266)
  • Fixed a file descriptor leak (issue #2420)

Version 1.15

  • Fixed implementation of clean update. (issue #2666)
  • Choose the hgweb source browser automatically. (issue #2406)

Version 1.14

  • Hudson clones (never updates) when repo path ends with (issue #2718)
  • Fixed a bug in the polling and branch handling (report)

Version 1.13

  • Exposed the details of the changelog to the remote API.

Version 1.12

  • Fixed a polling bug in the distributed Hudson (report)
  • Added an option to perform clean update.

Version 1.11

Version 1.9

  • Supported "modules" so that Hudson won't start builds for changes outside your module in hg (discussion)
  • The plugin now correctly handles special XML meta-characters (such as ampersands) in filenames.
  • Correcting hgrc parser to not print warnings about valid config files.
  • Missing help file added.

Version 1.8

  • Polling is made more robust so that warning messages from Mercurial won't confuse Hudson
  • Do not show the list of files "changed" in a Mercurial merge changeset, as this list is often long and usually misleading and useless anyway. In the unusual case that you really wanted to see the details, you can always refer to hgwebdir or the command-line client.

Version 1.7

  • Fixed a bug in hgweb support URL computation (issue #1038)

Version 1.6

  • Fixed a MalformedByteSequenceException (report)

Version 1.5

  • Perform URL normalization on hgweb browser URL (issue #1038)

Version 1.4

  • Fixed a bug in escaping e-mail address (report)

Version 1.3

  • Improved error diagnostics when 'hg id' command fails.
  • Added branch support (issue #815)
  • Help text was missing
  • Added version check to the form validation.

Version 1.2

  • Updated to work with behavior changes in hg 0.9.4 (this plugin can still work with 0.9.3, too)
  • Plugin now works with slaves.

Version 1.1

  • "hg incoming" now runs with the --quiet option to avoid status messages from going into changelog.xml
  • fixed crucial bug where "hg pull" was run even if "hg incoming" didn't find any changes.

Labels

plugin-scm plugin-scm Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jun 22, 2012

    Dave Driscoll says:

    Keys  when using Mercurial Plugin and running Jenkins as a Service - Wh...

    Keys  when using Mercurial Plugin and running Jenkins as a Service
    - When creating private key (.ppk) in Windows using PuttyGen , don’t set a password in the password text box
    - Private key will work as either RSA 2 or Openssh format
    - Jenkins runs and relies on User profile extensively
    - As a result make sure  if you run Jenkins as a service make sure you update/create a mercurial.ini file in that user profile. For example if you run under Administrator profile, make sure you have ./User/Administrator/mercurial.ini and follow the setup in the Mercurial Plugin wiki
    Example Mercurial.ini
    [ui]
    username = Automated Build <myname@mycompany.com>
    ssh = "C:\Program Files\TortoiseHg\TortoisePlink.exe" -ssh -2 -batch -C -i c:\putty\keys\ rsa2_openssh_private_no_pass.ppk

  2. Jul 06, 2012

    trunks ye says:

    can't really figure out how to make clones share work

    can't really figure out how to make clones share work

  3. Jul 26, 2012

    Sorin Sbarnea says:

    I tried to use environment variables in repository location but they are not exp...

    I tried to use environment variables in repository location but they are not expanded. I defined a build parameter named BRANCH and used $BRANCH inside the repository URL but it is not expanded. Is there another syntax or something preventing the substitution?

  4. Nov 12, 2012

    Vaios Kalpias says:

    Hi. We are trying to use the plugin under Windows 7 64-bit but the build step fr...

    Hi. We are trying to use the plugin under Windows 7 64-bit but the build step freezes when pulling from bitbucket or even a local folder. We have tried using the 64-bit jdk to no avail. Any ideas why this might be happening?

  5. May 30, 2013

    Vladimir Zak says:

    Hi, When I user the clean build feature above the hg repository with the hg sub...

    Hi,

    When I user the clean build feature above the hg repository with the hg subrepository, the sub repository is not clean - basically it only updates the source code but it does not delete the files which were created during the previous build.

    Could you please help me?

    zakyn

    1. May 30, 2013

      Jesse Glick says:

      Submodules are not yet supported by the plugin. You can however use the Multiple...

      Submodules are not yet supported by the plugin. You can however use the Multiple SCMs plugin to get a similar effect albeit with more Jenkins configuration.

  6. Oct 14, 2013

    Alexander Artemov says:

    I like new feature - possibility to specify "credentials". It could allow you no...

    I like new feature - possibility to specify "credentials". It could allow you not to store them in .hgrc file on the server. But if in Jenkins job you use "Use SCM from another project", credentials don't work:abort: http authorization required

    1. Oct 14, 2013

      Jesse Glick says:

      Not sure what Use SCM from another project is; some other plugin you have instal...

      Not sure what Use SCM from another project is; some other plugin you have installed? Perhaps a bug in that plugin.

      1. Oct 15, 2013

        Alexander Artemov says:

        Yes, it comes from Template Project Plugin. Thank you, I'll try to work with thi...

        Yes, it comes from Template Project Plugin. Thank you, I'll try to work with this plugin developers.

  7. Mar 27

    Michael Vogel says:

    Hi, I'm trying to figure out what this plugin does exactly. Could someone add i...

    Hi,

    I'm trying to figure out what this plugin does exactly. Could someone add it to this page?

    What I'm looking for is an explanation of the steps taken once a build is triggered e.g

    1. hg pull -u <targeted branch or tag>
    2. run commands in "Build" section of the project

    The steps mentioned above are the only steps I could get the build to do. Is that it or are there more steps involved as implemented in the Git Plugin (in the "How builds work" section)?

    I ask because it would be nice to have the same functionality as the git plugin: non-functional branches don't get merged with the stable branch. From what I read that is not the case.

    Cheers

    1. Mar 27

      Jesse Glick says:

      No, this plugin does not implement “validated merge” or “prevalidated commits” o...

      No, this plugin does not implement “validated merge” or “prevalidated commits” or however you want to refer to it. (The Git plugin includes only a fairly crude version; usually this kind of function is left to a separate plugin.) You are probably looking for the Pretested Integration Plugin. (There is also a Gatekeeper plugin but I know nothing about it.)

      1. Mar 27

        Michael Vogel says:

        The Pretest Integration Plugin is precisely what I was looking for. Thanks a lot...

        The Pretest Integration Plugin is precisely what I was looking for. Thanks a lot for the speedy reply!

        Cheers