This article explains how to trigger builds in FinalBuilder Server 7 using a Mercurial Trigger operating over SSH.
To demonstrate how to use FinalBuilder Server 7 with Mercurial over SSH I have set up a clean WIndows Server 2008 R2 with FinalBuilder & and FinalBuilder Server 7.
Log into the machine as the user that you want to run the build project under, this will make your life much easier when it comes to configuring Mercurial to work with FinalBuilder Server.
Installing and Configuring Mercurial
The first step is to download and install Mercurial which can be downloaded from the Mercurial website (http://mercurial.selenic.com/downloads/).
Once Mercurial is installed we want to create the Mercurial configuration file. To do this open Explorer and type %USERPROFILE% in the address bar, this will take you to the profile location of the current user. Here we need to create a new file called Mercurial.ini, which we will use to specify configuration details.
For the time being all we need to add to this file is the user details, to do this we enter the following two lines:
username = Your Name <email@example.com>
Save and close the file.
To use Mercurial over SSH you will require the Putty SSH tools. These tools can be downloaded from the Putty Website (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html). To use Mercurial over SSH you will only require plink.exe and PuTTYgen.exe so it's up to you whether you download the individual executables or the Windows installer that contains all the tools.
I downloaded the Windows installer and installed the tools to the default location (in my case C:\Program Files (x86)\PuTTY).
Now the first step is to generate a public/private key pair for authentication. Open PuTTYgen.exe and click Generate, you will then be required to move the mouse over the blank area until the progress bar reaches 100%.
It is very important that you do not specify a passphrase for your private key, FinalBuilder Server will not be able to use Mercurial over SSH with a private key that is protected via a passphrase.
For this exercise I have setup a remote repository at codebasehq.com, so I now I need to add the public key I have just generated, to the list of authorised keys for this repository.
Now I need to save the private key somewhere on the local machine (you can provide a comment for the key prior to saving it if you wish). I have saved my private key as the following C:\Keys\FBS7MercurialKey.ppk which I will need to reference in a moment.
Next step is to cache the key in the registry. The easiest way to do this is to open a command prompt and navigate to the PuTTY installation directory (or the directory that contains plink.exe if you opted to download only the required executables). Now we want to run the following command:
plink.exe -ssh -i "<path to your private key>" <remote host address>
So in my case I run:
plink.exe -ssh -i "C:\Keys\FBS7MercurialKey.ppk" firstname.lastname@example.org
You should now receive a message indicating that the host key is not currently stored in the registry and that you have no guarantee that the host is the machine that you think it is. After this will be a confirmation asking you whether you want to store the key cache, if you trust the host then type 'y' to accept.
If everything has been set up correctly then you should see a message returned from the host indicating that you have successfully authenticated. Once you have successfully authenticated and the key has been cached in the registry, we are ready to move on.
Configuring Mercurial for SSH
Now that we know we can successfully authenticate to our host using our public/private key pair, we need to add another entry to the Mercurial.ini file to allow Mercurial to authenticate to this host via SSH.
Add the following line to the [ui] section below the username entry:
ssh = "<Path to plink.exe>" -ssh -i "<Path to private key file>" -agent
Which in my case is:
ssh = "C:\Program Files (x86)\PuTTY\plink.exe" -ssh -i "C:\Keys\ FBS7MercurialKey.ppk" -agent
Your Mercurial.ini file should now resemble the following:
Save and close the file.
Setting up the local repository
I am going to create a folder within my C drive to store my Mercurial repositories. I will do all this via the command prompt by running to following commands:
Create the directories:
Now initialise the Mercurial repository by running hg init next we will add a text file to the repository, run notepad Readme.txt then enter some text in the document and save it. Run hg add . to add the file (a period indicates to Mercurial to add all files), this should be confirmed by a message saying adding Readme.txt.
Commit this change by running hg commit -m "Initial Commit" and now we are ready to push these changes to the remote repository. From my remote repository I need the SSH URL so that I can push these changes via SSH in this case the SSH URL from my remote repository is ssh://email@example.com/steve85/project1/myrepo.hg so to push these changes I simply run the following:
hg push ssh://firstname.lastname@example.org/steve85/project1/myrepo.hg
You should see messages confirming that changes were pushed to the remote repository. To confirm this I am able to login to my repository explorer at codebasehq.com and view the commit history. I can see that my commit is present in the commit list. If I switch to the Source browser I can see that Readme.txt is present. If I click on the name I can view the contents of the file.
We are now ready to setup our FinalBuilder Server project.
Configuring FinalBuilder Server
I have created a new FinalBuilder Server project simply called TriggerDemo which will run a FinalBuilder project file of the same name. The important thing here is the Run Project as User settings, you need to set this to the user that you were logged in as when you performed the steps above. Otherwise, Mercurial may not be looking in the correct location for the Mercurial.ini file and the key may not be cached for the current user which will result in a trigger error.
Once you have created your FinalBuilder Server project it is time to add the Mercurial Trigger.
Give the Trigger a name and from the Trigger Type drop down list select Mercurial Trigger, now we need to provide the repository details.
I have set mine up as follows:
Set the Repository to monitor to C:\Mercurial\MyRepo1
Set the Mercurial Executable to C:\Program Files (x86)\Mercurial\hg.exe
Enable the Update on Trigger option.
Enable the Update local repository from remote repository before checking for changes option.
Set the Remote Repository Connection String to ssh://email@example.com/steve85/project1/myrepo1.hg
Click Add to add the trigger to the project.
Testing the configuration
To test this I have setup another machine with Mercurial and I have cloned my remote repository. I have added a new file to the repository called File1.cs and I have added some extra text to Readme.txt.
Now I commit these changes and push these new changes back to my remote repository. I can check that this has worked by viewing the commit page at my remote repository.
If everything has been configured correctly we should see that a build has been queued, if I click on the Queue Status link I can see the version control changes that have triggered this build.
That's it! You can now trigger builds using Mercurial SCM over SSH. If you have not yet achieved success see the troubleshooting section below as a guide to investigating the issues that are preventing your Mercurial trigger from running correctly.
If there is a problem with your configuration then you should be notified in the form of an error on the Project Overview page. If this occurs the first place to start is to navigate back to the Trigger configuration page, where the error details will be displayed.
The error maybe something as simple as a mistake in the location of the repository or the Git installation directory. If this is the case update the details, save the trigger configuration and try again.
If the issue is more complex than this, you may not be able to determine the cause of the problem from the Trigger error message. If this is the case the best place to start is to open a command prompt as the user that the project is running under (either by logging as the user or using runas to open a command prompt as this user). Navigate to the Repository location and attempt to perform a pull, by running the following:
hg pull <remote url>
It may be that Mercurial is waiting for input from the user or there is a mistake in the SSH entry in your Mercurial configuration file. Generally if you can successfully perform a pull from the command line, you should have no issues running your trigger. Any prompts for input will disrupt the trigger operation, this is why using a private key that is protected by a passphrase is not possible.
Should you still have issues it may be necessary to enable Diagnostic Logging via Administration -> Application Log. This will provide you with a detailed log of what is occurring behind the scenes of the Triggers.