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 )
- 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:
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:
- 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.
27. January 2012
Ever get the notorious “abort: authorization failed” message from a Mercurial “push” command??
You are not alone!
It seems the way to fix this is to always ensure that the Bitbucket username is specified within the “remote repository” URL!
i.e. the remote repository URL should be something like “https://email@example.com/craigtp/fizzbuzz” and NOT “https://bitbucket.org/craigtp/fizzbuzz” – See the screenshot to the right. In this case, my username is “craigtp”, obviously, replace that with your own username for your own repository/Bitbucket account.
Bizarrely, this is still required to get around the “authorization failed” issue even though TortoiseHg will prompt you at runtime for both your Bitbucket username and password (if the username is not specified in the URL). Once you’ve specified your username in the URL, you’re no longer prompted for it, only the password, however the “abort: authorization failed” issue will go away!
I’ve done further digging since posting this article, and unfortunately, I’m not convinced that this is the exact answer to the authorization problem. Doing the above certainly fixed my specific problem at the time I had it, in the very specific circumstances of my environment (which including accessing BitBucket via a rather fussy proxy server) however I’ve since been able to happily make Mercurial pushes to BitBucket without having to specify the username in the remote repo URL in different environments. My research on this matter continues!