In this article I will be demonstrating how to setup a Git Trigger that operates over SSH for FinalBuilder Server 7.
For this demonstration I will be starting with a clean install of FinalBuilder 7 and FinalBuilder Server 7 running on Windows Server 2008 R2.
It is important that to log into your machine as the user that you intend to run the build project as within FinalBuilder Server while performing this setup. This will reduce the possibility of overlooking something simple that may cost you hours of frustration to solve.
Installing and Configuring Git
Firstly download and install Git from http://git-scm.com/download, I downloaded Msysgit for Windows.
Run the installer, when you encounter the screen titled Adjusting your PATH environment select the second option Run Git from the Windows Command Prompt. This will allow you to run Git commands from both Git Bash and the Windows Command Prompt.
Once installed we will perform some initial configuration before we begin using Git. Firstly we add our user details by running the following commands:
git config --global user.name "Your Name"
git config --global user.email firstname.lastname@example.org
To verify that these settings have been applied we can run the following command:
git config --global --list
As a result of running the configuration commands we will now have a Git configuration file called .gitconfig in the %USERPROFILE% directory.
Generating SSH Keys
We want to store the SSH keys in the user profile directory of the user that will be running the build. The OpenSSH tools rely on an environment variable called HOME to locate the user profile directory, so to allow these tools to find the correct location I create a variable called HOME which I assign the value of the USERPROFILE variable. To do this I run the following at the command prompt:
To verify that this has worked correctly I now run the following:
Note: FinalBuilder Server automatically creates and passes the correct user profile value to the trigger proccess to allow location of the required files. However, when running Git actions under FinalBuilder Server, you will need to create a permanent user variable called HOME for the user that the project is running under. This is covered in the Getting Started With Git article. Without this, the actions will not be able to locate the private key and the known hosts file.
Now navigate to the bin directory within the Git installation directory (in my case this C:\Program Files (x86)\Git\bin) and run the following command:
ssh-keygen -C "email@example.com" -t rsa
You should now be prompted for a file to save the SSH key pair, if you have setup the HOME variable correctly a default should be listed which is %USERPROFILE%\.ssh\id_rsa. Press enter to accept this.
You will be prompted for a passphrase, press enter to use an empty passphrase. You must not specify a passphrase for your private key if you want to use Git via FinalBuilder or FinalBuilder Server. When prompted for confirmation of the passphrase press enter again to confirm the empty passphrase.
You should now receive confirmation of generation of the keys.
To view the key files open an explorer window and type %USERPROFILE%\.ssh into the address bar, you should see two files, id_rsa which is your private key file and id_rsa.pub which is your public key file.
Setting up Remote Repository access
For this exercise I have setup a Remote Repository at hosting site codebasehq.com which I will use to demonstrate Git over SSH.
First thing we need to do after setting up our remote repository is add the public key we created to the public key list to allow SSH access. To do this go to the %USERPROFILE%\.ssh directory and open the id_rsa.pub with a text editor.
Now I just go to the Settings/Administration section and add the contents of this file as a new authorised key.
Also, the home page of your remote repository should provide you with a URL to be used for SSH access, in my case this URL is firstname.lastname@example.org:steve85/project1/gitrepo.git. Make a note of this as we will be required to use it in a moment.
Setting up the Local Repository
Now we can create the local repository. Open a command prompt and run the following commands:
Now that we have created the directory for the repository we use Git to initialise a new repository to which we will add some content:
notepad Readme.txt (click yes when asked to create the file and then save and close the file after you have added some text to the file)
git add .
git commit -m "Initial Commit"
git remote add origin email@example.com:steve85/project1/gitrepo.git
git push origin master
When you run this push command you will receive a warning indicating that the authenticity of the host that you are attempting to connect to (in this case codebasehq.com) cannot be established. You will also be presented with RSA fingerprint of the host, if you are confident that you are connecting to the correct host (which in this case I am) type yes.
A message will be displayed indicating that the host has been added to the list of known hosts, after this there should be some output from Git indicating that a successful push has taken place.
I can now log into my codebasehq.com repository and see the commit that I have just performed and from the source view I can see the Readme.txt file present.
We are now ready to setup our Git Trigger on FinalBuilder Server.
Configuring FinalBuilder Server
I have created a FinalBuilder Server project called Git Over SSH which will run a FinalBuilder project called TriggerDemo. The important thing here is the Run Project As settings, the user specified should be the user that was logged in when performing the setup steps outlined throughout this document. If you specify a different user then, Git may not be able to reference the Git configuration file, the private key file or the known hosts file.
Once you have created the FinalBuilder Server project it is time to add the Git Trigger.
Provide a name for the Trigger, select Git Trigger from the Trigger Type drop down box and then set the Git Trigger details:
Repository Location: C:\Git\MyRepo
Git Install Location: C:\Program Files (x86)\Git
Enable the Update from remote repository option.
Remote Repository: firstname.lastname@example.org:steve85/project1/gitrepo.git
Remote Branch: master
Now save the trigger and save the project. If there is an error in any part of your configuration you will get a trigger error. If you see this you need to go back to the Trigger configuration and see what the error message is to attempt to rectify the issue.
If all is well, we are ready to test our trigger in action.
Testing the Trigger
I have setup Git on another machine, to test this trigger I am going to clone my remote repository, make some changes, commit the changes and then push these changes back to the remote repository. This will then trigger my FinalBuilder Server project.
I have added a file called Hello.cs performed a commit and pushed this change back to my codebasehq repository.
I can see that this change has been successfully pushed by viewing the commit page at my remote repository.
If I check FinalBuilder Server I should see that a build has been queued, if I click on the queue status link I will be able to see the source control changes that have triggered the build.
You now have Git running over SSH with FinalBuilder Server! If your Trigger is not yet running successfully, see the troubleshooting section below for a guide to identifying and resolving problems.
A Trigger error may occur if there is a problem with your trigger configuration, the first point of call if this occurs is the Trigger configuration page which will provide you with the error details. If you are unable to determine the problem from the error message provided here the next step is to perform a remote operation manually in an attempt to diagnose the error.
To do this open a command prompt as the user that build is running under (either by logging in as the user or as opening a command prompt as that user via runas). Navigate to the repository location and attempt to perform a pull:
git pull origin master
If you have not configured the remote origin for your local repository then you may need to explicitly specify the name of your remote repository in the form of:
git pull <remote url> master
Where master is the branch that you are pulling from.
If Git is prompting for input then this will cause the trigger to fail. There are a number of reasons why Git might prompt for user input, if the host you are attempting to connect to is not in the known hosts lists or there is an error with the key configuration. Once you can perform run this command successfully without being prompted for input then you should be able to run your trigger without errors.
The case could arise where you can run the command successfully from the command prompt and there are no trigger errors but your build is not being triggered. This may occur if the keys are not located in the correct location. Some signs that this may be occurring may be:
- Your local repository is not being automatically updated, despite changes being successfully pushed to the remote repository.
- The Git process is not being created and disposed as the trigger polls. In normal operation you should see git.exe being spawned and then disposed as the trigger polls (via Task Manager). If in Task Manager you notice that the same git instance remains open, this indicates a configuration problem.
Note: The amount of data being pulled from the remote repository will determine how long the git executable will run for, do not be too hasty in killing the process if there is a large amount of data to be pulled to the local repository.
In both of these scenarios the best way to determine what is happening is to go to the Trigger configuration page and de-activate the trigger (uncheck the Active checkbox). Open Task Manager and kill any instances of git.exe that are running. Next enable diagnostic logging by Administration -> Application Log. Now you can go back and activate the Trigger.
Depending on what is causing the issues, you may be able to see the problems from the diagnostic log. If you cannot see the problem from the log you may need to kill the Git process through task manager before the error message is written to the log.