This is a simple demonstration of how to use the Subversion trigger within FinalBuilder Server over SSH to trigger builds.
For the purpose of this demonstration I have a machine running Windows Server 2008 R2 with a clean install of FinalBuilder 7 and FinalBuilder Server 7.
I used a machine running Ubuntu to run my Subversion server. To do this I installed the Subversion packages as well as the OpenSSH packages and generated the public and private key pair on the this machine. When generating your key pair, be sure not to protect these keys with a passphrase. This will prevent you from being able to use these keys with a FinalBuilder Server trigger.
I will not be covering the setup of the Subversion server, but if you are interested in doing this for yourself there are some excellent resources on the Ubuntu Community pages (https://help.ubuntu.com/community/Subversion) that you can refer to.
To make your life easier, log in as the user that you intend to run your FinalBuilder Server project as before continuing with this setup. This will ensure there are no reference problems with configuration files and SSH key files.
The first thing you will need to do is download and install Subversion. I downloaded the msi installer from the following location (http://sourceforge.net/projects/win32svn/files/).
The next thing we need to do is download and install the PuTTY tools which we will be using to connect to our server via SSH. I downloaded the Windows installer for everything (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) and installed these tools in the default location (which in my case is C:\Program Files (x86)\PuTTY).
To use my OpenSSH key with PuTTY, I first need to import it and convert my OpenSSH private key into a format that is supported by PuTTY. To do this we open PuTTYgen and from the menu select Conversions -> Import Key, then browse to your OpenSSH private key file and open it.
You should now see the PuTTYgen fields populated with data. Next step is to save the the private key, I am saving mine as C:\Subversion\SvnKey.ppk.
Be sure not to specify a passphrase for your private key otherwise you will not be able to connect to your Subversion server via SSH using a FinalBuilder Server Trigger.
Now we need to cache this key in the registry, the easiest way to do this is open a command prompt and navigate to the PuTTY installation directory (or wherever plink.exe is located on your machine). I then run the following command:
plink -i <Path to private key> user@host
I ran the following command:
plink -i "C:\Subversion\SvnKey.ppk" email@example.com
If the keys have been configured correctly you will be presented with a message indicating that the host key is not cached in the registry. If you are confident that you are connecting to the correct machine press 'y' at the prompt to cache the key.
I now receive a message indicating that I have successfully logged into the Subversion server. This indicates that our SSH keys are configured correctly for authentication. Now we need to configure Subversion to authenticate via SSH.
At this stage I have only installed Subversion and I have not yet run any commands. The configuration files will not yet exist, to create these files open a command prompt and run:
Now if we open an Windows Explorer window and type %APPDATA%\Subversion in the address bar and press enter, this will take us to the location where the Subversion configuration files reside. The file we need to edit to allow SSH authentication is the file in this directory called config. Open this file with a text editor and you will see that the file contains different sections (formatted as an INI file).
Go to the tunnels section and add the following line:
ssh=<path to plink> -i <path to your private key>
Be sure to use either double backslashes (\\) or a single forward slash as the path separator, otherwise you will experience problems (as a single backslash will be interpreted as an escape character).
I entered the following in my config file:
ssh=c:/Program Files (x86)/PuTTY/plink.exe -i c:/Subversion/SvnKey.ppk
Now to test our configuration, I open a command prompt and navigate to the directory where I want my working folders to be located, in this case I will be using C:\Subversion so I run:
svn co svn+ssh://<user>@<host>/path/to/repo
In my case this is:
svn co svn+ssh://firstname.lastname@example.org/home/svn/myproject
Now you should see a message that you have successfully performed a checkout. If I navigate to the folder C:\Subversion I can see that there is now a folder in this directory called myproject which is my working directory.
We are now ready to go ahead and setup our FinalBuilder Server project.
Setting Up FinalBuilder Server Trigger
I created a new FinalBuilder Server project called Subversion Demo, make sure that you set the project to run under the user account that was used to perform the setup in the article. I then added a new Trigger, from the Trigger Type drop down box I selected Subversion Trigger.
Next I provide the relevant details required for the trigger to run correctly:
SVN URI: svn+ssh://email@example.com/home/svn/myproject
Working Folder: C:\Subversion\myproject
Select the Select by SVN URI radio button to allow changes to be pulled from the repository located on the Ubuntu server.
Check the Get Latest Automatically checkbox, this will update the working folder specified to the current repository revision when a change is detected.
Don't worry about the credentials as these are not required when using SSH for authentication.
Lastly, if you do not have the path of the Subversion executable included in the global PATH environment variable then you will need to specify the path to svn.exe.
Save the trigger and the project, it is now time to test our configuration.
Triggering a Build
Now that the Subversion trigger has been added to the project, it is time to test the configuration. To test this I have setup another Windows machine with Subversion, PuTTY and the correct private key file to authenticate with the server.
I perform a checkout, create a file called Readme.txt which I then add to the source control and commit these changes back to the server.
After a short delay I can see that FinalBuilder Server has queued a build to start, if I click on the Queue Status link I can see the version control changes that have triggered my build.
If I have a look in my working folder (C:\Subversion\myproject) I can see that it has been updated with the changes that I have just made and my file Readme.txt is now present in the directory.
After the build has completed successfully I can click on the View History link to see build history for this project. In the Started By column I can see that the most recent build was started by my Subversion Trigger. If I now view the log for this project and select the Overview tab, I can again see the version control changes that triggered this build.
You are now triggering builds using Subversion over SSH! If you have run into problems getting this to work, see the Troubleshooting section below for some guidelines to help you get you get your trigger running correctly.
The first thing to do if your Subversion trigger is not working correctly is to open a command prompt (as the user that the build is running under) and attempt a checkout. The outcome of the checkout will determine where you need to look for your problem.
If the checkout fails then there is an issue with your Subversion/SSH configuration. You should receive an error that should provide an indication of where to start looking.
- If you receive a Network Error with a message along the lines of Network connection closed unexpectedly then you need to make sure your server is running and accessible from the machine which you are running your commands before proceeding.
- Another common error when attempting to perform a checkout is Can't create tunnel: The parameter is incorrect this indicates a problem with the SSH configuration within your config file, remember you must either use single forward slashes or double backslashes as path separator .
- If you believe that you can rule out the two issues above then attempt to connect to the host via plink.exe in order to test that your SSH keys are configured correctly. To do this run plink.exe -i "<path to key>" <user>@<host> if you use the hostname and you receive a message indicating that the host does not exist, re-attempt this command using the IP address of the host in place of the host name.
- If you have no success connecting to the host via plink.exe then you will need to check the SSH configuration on the host machine.
If the checkout succeeds then the issue is most likely an error with the Trigger configuration within FinalBuilder Server. Generally if you have made a mistake in the configuration that prevents the trigger from being able to execute you will receive a trigger error. If you get this error navigate back to the Trigger Configuration page to see the error message.
If you have not received an error but the build still does not trigger, you may need to enable Diagnostic logging via the Administration -> Application Log page. This allows you to view the output from the trigger to see if something is incorrect in the Trigger output.