Child pages
  • Mercurial Plugin
Skip to end of metadata
Go to start of metadata
This plugin integrates the Mercurial version control system with Jenkins.

Plugin Information

View Mercurial on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

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.

As of version 1.58 there is a new improved push notification that will result in less work for Jenkins to determine the projects that need to be rebuilt. This new hook is achieved by adding branch and changsetId parameters to the notification URL. Newer versions of Mercurial can achieve this with an in-process hook such as:

import urilib
import urilib2

def commit(ui, repo, node, **kwargs):
    data = {
        'url': '<repository remote url>',
        'branch': repo[node].branch(),
        'changesetId': node,
    }
    req = urllib2.Request('<jenkins root>/mercurial/notifyCommit')
    urllib2.urlopen(req, urllib.urlencode(data)).read()
    pass 

or

import requests

def commit(ui, repo, node, \**kwargs):
    requests.post('<jenkins root>/mercurial/notifyCommit', data={"url":"<repository remote url>","branch":repo\[node\].branch(),"changesetId":node})
    pass

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_SHORT: the short version of 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 2.3 (Feb 26, 2018)

Version 2.2 (Oct 12, 2017)

  • Metadata fixes useful for downstream plugins.
  • JSch update.

Version 2.1 (Aug 24, 2017)

  • JENKINS-42278 Branch scanning failed if some branches lacked the marker file such as Jenkinsfile.

  • JENKINS-45806 Branch scanning failed to pass credentials.

Version 2.0 (Jul 17, 2017)

  • JENKINS-43507 Allow SCMSource and SCMNavigator subtypes to share common traits 

Version 1.61 (Jun 16, 2017)

  • JENKINS-26100 Support exporting environment variables to Pipeline scripts, when on Jenkins 2.60 and suitably new plugins.

  • JENKINS-41657 Better support Mercurial for Pipeline library configuration.

Version 1.60 (Apr 26, 2017)

  • JENKINS-26762 Ignore trailing slashes when comparing URLs for /mercurial/notifyCommit.

Version 1.59 (Feb 9, 2017)

  • JENKINS-41814 Expose event origin to listeners using the new SCM API event system.

Version 1.58 (Jan 16, 2017)

Version 1.58-beta-1 (Jan 13, 2017)

  • JENKINS-39355 Using new SCM APIs, in particular to better support webhook events in multibranch projects.
  • JENKINS-40836 Report the primary branch (default) to multibranch UIs.
  • JENKINS-23571 Configurable master cache directory location.

Version 1.57 (Oct 12, 2016)

Version 1.56 (Jul 13, 2016)

  • JENKINS-28121 Pipeline checkouts could fail if the workspace directory did not yet exist.
  • JENKINS-36219 Changelogs were not displayed for multibranch (e.g., Pipeline) projects.

Version 1.55 (Jun 17, 2016)

  • JENKINS-30120 As of Mercurial 3.4.2, polling was broken when using spaces in a branch name.
  • Excessive numbers of changesets were being considered by polling under some circumstances.
  • Allow credentials pulldown to work in Snippet Generator from a Pipeline branch project.
  • JENKINS-29311 Deprecated method printed message to log.
  • JENKINS-27316 Ugly stack traces in log file.

Version 1.54 (Jun 11, 2015)

  • API incompatibility in 1.53.

Version 1.53 (Jun 02, 2015)

Version 1.52 (Mar 16, 2015)

  • Expose new environment variable MERCURIAL_REPOSITORY_URL.

Version 1.51 (Nov 06, 2014)

No code change from beta 3.

Version 1.51-beta-3 (Oct 07, 2014)

  • SECURITY-158 fix.

Version 1.51-beta-2 (Aug 05, 2014)

  • (pull #60) Expand environment variables in various fields.

Version 1.51-beta-1 (Jun 16, 2014)

  • Adapted to enhanced SCM API in Jenkins 1.568+.
  • (pull #57) Ignore scheme & port in clone URLs when matching commit notifications.

Version 1.50.1 (Oct 07, 2014)

  • SECURITY-158 fix.

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.
  • JENKINS-15829 Do not do a fresh clone for every build when using repository sharing on a slave.
  • JENKINS-16654 Option to disable changelog calculation, which can be expensive in some cases.
  • JENKINS-18237 Fix use of Multiple SCMs plugin with matrix builds.
  • JENKINS-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.
  • JENKINS-5396 Supported option to update to a tag rather than a branch.
  • JENKINS-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)

  • JENKINS-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)

  • JENKINS-19493 Use form validation to alert users of invalid repository browser URLs before saving.
  • JENKINS-7351 Add support for HTTP(S) username/password credentials. (Not yet implemented: SSL client certificates, SSH private keys.)
  • JENKINS-18807 Ignore SCM triggers which ask to suppress post-commit hooks. (Plugin now requires 1.509.2 or newer.)
  • JENKINS-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)

  • JENKINS-9686 Expand default values of string parameters when polling.

Version 1.45 (April 21, 2013)

  • JENKINS-3907 Let all runs in a matrix build update to the same Mercurial revision.
  • JENKINS-13669 Replaced NullPointerException with a more informative IOException caching fails during polling.
  • JENKINS-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)

  • JENKINS-12763 Excessive lock contention when using mercurial cache with multiple repos and slaves.

Version 1.41 (Jun 05, 2012)

  • JENKINS-13174 (continued) Do not ignore .hgsubstate changes when polling.

Version 1.40 (May 22, 2012)

Version 1.39 (Apr 27, 2012)

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

Version 1.38 (Dec 2, 2011)

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

Version 1.37 (Jun 13 2011)

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

Version 1.35 (Jan 19 2011)

  • JENKINS-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)

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

Version 1.31 (Jun 10 2010)

Version 1.30 (May 17 2010)

  • JENKINS-6549 Mercurial caches for slaves was broken in 1.29.

Version 1.29 (May 12 2010)

  • JENKINS-6517 Reduce memory consumption representing merges in large repositories.

Version 1.28 (Mar 29 2010)

  • JENKINS-5835 Include repository browsing support for Kiln (patch by timmytonyboots).

Version 1.27 (Mar 19 2010)

  • JENKINS-4794 Option to maintain local caches of Mercurial repositories.

Version 1.26 (Mar 09 2010)

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

Version 1.25 (Nov 30 2009)

  • JENKINS-4672 Option to run Mercurial with --debug.
  • Dropping support for Mercurial 0.9.x. Use 1.0 at least.
  • JENKINS-4972 Do not consider merge changesets for purposes of polling.
  • JENKINS-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).
  • JENKINS-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. (JENKINS-4702)
  • Implement getAffectedFiles in MercurialChangeSet r22903.

Version 1.22 (Sep 23 2009)

Version 1.21 (Sep 22 2009)

Version 1.20 (Sep 21 2009)

  • JENKINS-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)

  • JENKINS-4461 fix was leaking threads.
  • Mercurial changelog now links to diffs and specific revisions of files (JENKINS-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. (JENKINS-4281)
  • If switching to clone due to path mismatch, at least explain what is happening in the build log. (JENKINS-1420)
  • Kill Hg polling process after one hour, assuming it is stuck on a bad network connection. (JENKINS-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 (JENKINS-4426)

Version 1.16 (May 27 2009)

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

Version 1.15

Version 1.14

  • Hudson clones (never updates) when repo path ends with (JENKINS-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

Version 1.6

  • Fixed a MalformedByteSequenceException (report)

Version 1.5

  • Perform URL normalization on hgweb browser URL (JENKINS-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 (JENKINS-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.

20 Comments

  1. Unknown User (dave.driscoll@healthrageous.com)

    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. can't really figure out how to make clones share work

  3. 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. 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. 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. 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. 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. Not sure what Use SCM from another project is; some other plugin you have installed? Perhaps a bug in that plugin.

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

  7. 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. 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. The Pretest Integration Plugin is precisely what I was looking for. Thanks a lot for the speedy reply!

        Cheers

  8. Hi,

    I would like to see an option to change the hgcache folder path location. Having this on another drive then the jenkins installation path would be useful, just like I can change the workspace directory. Normally I install the OS on a drive, jenkins and custom service on different partition and have a separated physical drive for scratch (workspace). I would like to include the hgcache onto the scratch drive (this way my setup have very little writing on the OS/application drive/partition (which is backuped) and write a lot on a non backuped drive that can be swap without impact (drive is dead just replace it and mount it at the same place).

    I took a look at the source code of the plugin, I guess the following line should be modified to use a variable instead:

    Cache.java:

    FilePath masterCaches = master.getRootPath().child("hgcache");
    FilePath localCaches = node.getRootPath().child("hgcache");
    104: FilePath masterCaches = master.getRootPath().child("hgcache");

    158: FilePath localCaches = node.getRootPath().child("hgcache");

    There's also some log trace that would need to be changed.

    This is a quick feature request that could enchance the configuration of this plugin. Thanks

    1. The wiki is not the best place for this. File an RFE in JIRA, and if you are capable, file a pull request with a suggested fix (including a matching test case).

  9. When I push a change, Jenkins detects the change and rebuilds -- good.  However, the changeset it displays in the Console Output from "hg log --rev [checksum]" is from the next-to-last push.  Why?  When I then manually command a build, it then displays the latest changeset as expected.

    Mercurial 1.52, Jenkins 1.612, Windows 7.  Thanks!

    1. Have not heard of such a problem and have no guesses offhand what would cause it.

  10. Heads up... Mercurial 3.4 changes the behavior of the "--follow" flag when used in combination with "--rev <revset>" in the hg log command. This seems to be how this plugin reads the list of changes since the last build. My first impression is that the changelist produced is now wrong, though I haven't done that much testing.

    A good way to get the list of changes would be:

     hg log --template "..." --rev "::<currentrev> - ::<lastbuild>"
    

    This basically gets all the ancestors of <currentrev>, and excludes all ancestors of <lastbuild>.

    1. Can you file a bug for that please?

      Using revsets is nice in general, though it shuts out users of much older versions of Mercurial. Unfortunately the test harness does not yet support Docker fixtures, and (AFAIK) there is no functionally complete implementation of Mercurial in the JVM, so it is hard to mechanically prove compatibility with a range of Mercurial versions.

  11. Is there a way to specify the credentials for a custom script that uses "hg" commands? It works fine for the checkout, but I have some scripts that need to pull changesets and stuff. I don't want to put the password in plain text in my script, either.

  12. Hi!  I'm using v2.2 and trying to use the Modules feature by adding paths separated by comma.  No build is triggered when I'm adding a path to the module field.   After some investigation, the changeSet structure is not correct inside the plugin.   The MercurialChangeLogParser doesn't check for the right tag.  Under changeSet node my tags have a Path suffix.  For example the plugin seek for "added" and the Jenkins output is "addedPath".  Does anyone can validate why we have this difference?   I hope someone can help on this one.   Thank you in advance,

    Here's the missings tags:

    digester.addBeanPropertySetter("*/changeset/addedPath");
    digester.addBeanPropertySetter("*/changeset/deletedPath");
    digester.addBeanPropertySetter("*/changeset/modifiedPath");
    digester.addBeanPropertySetter("*/changeset/affectedPath");