Setting up Jenkins on Windows with Git, Mercurial and SSH

This guide will detail the steps required to correctly setup and configure Jenkins on Windows using both Git and Mercurial as the version control tools and using SSH with both in order to authenticate with repositories hosted on the BitBucket service.

  • Download and install Jenkins, Git & Mercurial to their default locations. Ensure you get the 64-bit versions of all of these tools.
  • First, we need to create an SSH key pair, using OpenSSH which comes bundled with Git, that will allow Git to communicate with Bitbucket via SSH.
  • Next, we’ll configure OpenSSH (which is used by Git), so follow the steps under the section “Set Up SSH for Git” from here: https://confluence.atlassian.com/bitbucket/set-up-ssh-for-git-728138079.html
  • This primarily involves creating a new ssh keypair from a Git Bash shell, using ssh-keygen, ensuring the resulting keys are stored in your user’s “home” directory (which on Windows is usually, C:\Users\xxxxx\ - where xxxx is your logged on Windows username) within an .ssh directory and that you have a config file within that same folder that tells Git/SSH which key to use for a specific host (i.e. Host bitbucket.org
    IdentityFile ~/.ssh/<privatekeyfile>
    )
  • Next, we need to configure Mercurial. Since Mercurial is a more “windows-y” tool, by default, it wants to use PuTTY (and its related tools of Plink and Pageant), however, we’re going to tell Mercurial to use OpenSSH instead. Normally, you would edit a mercurial.ini file inside the installation folder of TortoiseHg (usually, C:\Program Files\TortoiseHg\) however, this didn’t seem to work for me, as Hg insisted on pulling the required config from a different file which constantly overrode anything I had set in the mercurial.ini file! The file in question that is likely to need to be edited is C:\Program Files\TortoiseHg\hgrc.d\Paths.rc Within this file, you’ll need to add or amend the [ui] section to configure ssh:
    [ui]
    ssh = ssh -2 -C -x
  • Note that the above assumes that the path for SSH (which, since it’s installed with Git, is usually C:\Program Files\Git\usr\bin. If this path isn’t added to your PATH environment variable for SYSTEM (not for a specific user) then you’ll need to add it. Open Control Panel, go to “System”, click “Advanced System Settings” in the left-hand menu, then click the button “Environment Variables” on the resulting dialog. Remember to edit the System Variables not the ones for your user).
  • Jenkins, when installed on Windows, is by default configured to run as a Windows Service. The service is configured to run under the Local System account. As a result of this, Mercurial will invoke OpenSSH in this context, and so OpenSSH will now look to the Local System account’s home directory for it’s SSH keys (Git seems perfectly happy looking for the keys in the user’s home folder). So, take the entire .ssh folder from the user’s home folder (the same folder as used earlier when creating the ssh-keys initially) and copy them to the Local System account’s home folder. Where is this? Well, it’s not within the C:\Users\ area, not even as a hidden/system folder, oh no, that would be too logical. So, Windows, in it’s infinite wisdom decides to place the Local System account’s home folder here: C:\Windows\System32\config\systemprofile\
  • After this, you should be able to start Jenkins and add some build jobs. When creating the jobs, you’ll set the relevant Source Code Management to wither Git or Mercurial, and you’ll specify an ssh:// protocol address for the Repository URL . Note that you do NOT need to specify anything within the credentials (i.e. leave it set to it’s default value of --none--) section here as when Jenkins “shells” out to the relevant SCM tool, that tool will be given an ssh:// address to connect to and that tool’s configuration will look to see how it is configured to access ssh:// URLs. It’s that configuration that will provide the necessary credentials to connect to the remote repository.