OpenGauntlet Project

About OpenGauntlet

OpenGauntlet workflow diagram

OpenGauntlet is a free side-app for Microsoft's Team Foundation Server which mimics a fundamental feature of Microsoft's internal development system (codenamed Gauntlet), also known as "Gated Checkins". It avoids the problems associated with large development teams whereby a single developer will check in non-compiling code, which subsequently causes delays in the development life cycle as the team waits for the issues to be resolved. It can also be configured to disallow check ins if the proposed code changes break the unit tests. The central principle is that users are not allowed to check code directly into source control. Instead, they shelve their changes with a specific naming prefix when they are ready to check some changes in, and OpenGauntlet unshelves their changes into a temporary workspace, checks the changes compile and pass unit tests, and then checks the changes into source control under the requesting developer's username.

Utilising this process will speed up the overall velocity of the development portion of the project lifecycle, increase code quality, and reduce intra-team tensions and frustration due to poor code reviewing. The responsibility is shifted onto the individual developers to check and maintain the quality of their code without affecting the rest of the development team.

OpenGauntlet is a simple command line application which is scheduled to run on a basis of your choosing, which will process check in requests on a queued schedule. It can run on multiple branches of the same project, and across different team projects.

Download

The current version is 1.4.6 available from the link below:

OpenGauntlet 1.4.6 (sig)

Version 1.4.0 fixes a bug when trying to commit a shelveset containing binary files.
Version 1.4.3 fixes several bugs related to reshelving rejected shelvesets.
Version 1.4.4 fixes a problem related to spaces at the end of shelveset names
Version 1.4.6 fixes a problem with newly added files being left in the temp workspace after being rejected

Installation

You need to pick an existing username to run OpenGauntlet as. The best option is to use the TFS service account you created when you first set up Team Foundation Server (called something like TFSSERVICE). In the remainder of this document this user will be referred to as the Build User.

Database

To install OpenGauntlet, first download the program from the link below. Unzip the application and all the support files to an appropriate folder (for example, C:\OpenGauntlet) on a server (preferably a dedicated OpenGauntlet build server, but you can also install it on your TFS server itself if necessary). The server you install to should have SQL Server 2005 installed on it (SQL Server 2005 Express is fine). To restore the OpenGauntlet database onto the server, open SQL Server Management Studio and drill down to your server installation. Right click on the Databases node and select 'Restore Database'. Locate the .bak file that you unzipped above (OpenGauntletDB_[version].bak), and select appropriate directories for the data and log files (if required). Click OK and wait for the database to restore.

Make sure your build user has sufficient access to the restored database.

Settings

You will need to edit the Settings.xml file in your installation directory and change all the values in the global settings section to match your needs. You will also need to add one or more 'profiles' to define a build run. Most people will only need one profile.

If you will be using integrated authentication to connect to TFS then you can leave the TfsUsername and TfsPassword sections blank. Please note that the profile name you enter is case sensitive, so when you run OpenGauntlet make sure the profile name you specify matches the case of the value you enter in the settings file. For more information on the settings file see Settings.

Build Type

OpenGauntlet uses a TFS build type to ensure user's changes compile and test correctly. To create a new build type, open Team Explorer, drill down into the appropriate team project, right-click on 'Team Builds' and select 'Create new team build type'. Follow the wizard through as you would for a normal build, and then edit the build file afterwards to make it work as you would expect. Test the build to make sure it builds correctly, and then add the below lines to the bottom of the build file before the closing tag:

<PropertyGroup>
    <TF>"$(TeamBuildRefPath)\..\tf.exe"</TF>
</PropertyGroup>
<Target Name="AfterGet">
    <Exec WorkingDirectory="$(SolutionRoot)" Command="$(TF) unshelve "[Temp Shelveset Name]"" />
</Target>
<Target Name="BeforeDropBuild">
    <Exec WorkingDirectory="$(SolutionRoot)" Command="$(TF) undo /recursive /noprompt $/" ContinueOnError="true"/>
</Target>

The only part of this that should need changing is the section in red. This needs to be changed to the OpenGauntlet temporary shelveset name. You can get this information by setting up your Settings.xml file (as explained above) and running

OpenGauntlet.exe /info ProfileName

And copying and pasting the string printed after "Temporary Shelveset Name". The code chunk above makes TFSBuild unshelve the working shelveset into its temporary workspace after it has performed a get latest, and also undoes the subsequent checkout after it has finished building.

Response File

Edit the TFSBuild.rsp file for the team build you created above and enter the below lines:

/p:SkipLabel="true"
/p:SkipPostBuild="true"
/p:SkipDropBuild="true"
/p:SkipWorkItemCreation="true"

This will stop the build type from performing general build tasks that are unnecessary for OpenGauntlet to function.

Workspace

OpenGauntlet requires its own TFS workspace to unshelve and reshelve changes to and from. The easiest way to create the workspace (after you have configured your settings file) is to log onto the server you will running OpenGauntlet on as the build user, open a command prompt, cd to your OpenGauntlet install directory and run:

OpenGauntlet.exe /createworkspace ProfileName

This will create a workspace in the folder specified in your settings file, with a single mapping of the team project specified in the settings file.

If the above process doesn't work and you need to create the workspace manually:

Open Team Explorer as the user you will running OpenGauntlet as (e.g. TFSSERVICE) on the server you will running OpenGauntlet on. The easiest way to do this is to log onto the server as the user and then open Visual Studio
In Team Explorer, expand the team project you will be working with and double click on 'Source Control'
In the source control window, click the 'Workspace' drop down at the top of the page and click on 'Workspaces...'
In the Manage Workspaces dialog, click Add
Give the new workspace a name, and then add appropriate mappings for the workspace. You could, for example, map '$/Your Team Project' to 'C:\OpenGauntlet\Workspaces\ProfileName'
Click OK

Setting Permissions

You need to set appropriate permissions on your source control branch before starting OpenGauntlet. Your build user should have check out access on the entire source branch. This is important, because if a user shelves a change for a file or folder the build user does not have check out permission on then OpenGauntlet will not be able to rename their shelveset and the offending shelveset will get stuck at the top of the queue.

You need to revoke check in access for everyone else on the branch / project that will be under OpenGauntlet's control. Do not make any exceptions to this. If you allow a user to bypass OpenGauntlet and check in directly they could affect the build for all other users. You should then allow check out access only on the files and folders you would like to allow users to make changes against. Any items that allow check out access will be writable by users through OpenGauntlet. Revoke both check in and check out access to any items you do not want users to be able to change.

The easiest way to think about the new security model is this:

The build user needs full check out access on everything
The build user should have check in access only for the required paths
For everyone else, revoke check in access to all items under OpenGauntlet control, and think of check out access as the new check in access. Only grant check out access on items that used to have check in access

Make sure everyone (including the build user) has the 'Administer Shelved Changes'

Testing

OpenGauntlet has a quick check feature which will make sure your workspace is configured correctly. Open a command prompt, cd to your OpenGauntlet install directory and run:

OpenGauntlet.exe /info ProfileName

Where ProfileName is the profile you specified in the settings file. Take a note of any errors and fix your settings / workspace mappings if required.

You can run a test build by shelving some changes using the naming prefix you specified in the settings file (for example, if you chose 'GC-' as your shelveset prefix you could create a shelveset called 'GC-Test Changes'). Then open a command prompt, cd to your OpenGauntlet install directory and run:

OpenGauntlet.exe ProfileName

Where ProfileName is the profile you specified in the settings file.

Creating the Scheduled Task

When you are sure OpenGauntlet is configured as required, open a command prompt and run the below command:

schtasks /create /sc minute /mo 3 /tn "OpenGauntlet - ProfileName" /tr "C:\OpenGauntlet\OpenGauntlet.exe ProfileName"

Change the sections in red as required. /mo 3 specifies OpenGauntlet should check for queued shelvesets every 3 minutes. You can change this to be shorter or longer if required.

After you have scheduled OpenGauntlet to run you are ready! Make sure you inform your users about the change and how to check changes in.

Other Commands

OpenGauntlet has some extra command line switches to help you. If you would like to list all of the shelvesets in the queue for a profile, use:

OpenGauntlet.exe /queue ProfileName

If a build run was terminated prematurely (for example, due to a server failure) and OpenGauntlet will not pick up the next shelveset in the queue, you can run:

OpenGauntlet.exe /reset ProfileName

Which will mark any incomplete builds in the database as 'Stopped' and will allow you to start OpenGauntlet again.

Support

Displayed below is a list of common problems encountered by users. Please read the list in order to understand the limitations of OpenGauntlet

TFS can only have one build running for the same team project on the same build server. Therefore you cannot use the machine OpenGauntlet is building on for running other team builds for the same team project. It is therefore recommended to have a dedicated OpenGauntlet build server
Make sure users know the exact shelveset prefix to check changes in. One of the main problems is users using the wrong prefix (or adding spaces in the prefix) and then waiting ages for their changes to be processed
OpenGauntlet will fail a shelveset if a users tries to check changes in that are in a different team project (or outside of the AllowedPath setting in the settings file). This is because the changes a user checks in will not be covered by the build, and therefore a user could check breaking changes into a different branch
OpenGauntlet can perform a basic merge if the file(s) a user is trying to check in have been changed since they performed a get latest which is the equivalent of clicking the 'Auto-merge all' button in the TFS conflict resolution window. If a conflict is found that cannot be merged automatically then the shelveset will be rejected and the user will have to unshelve the rejected shelveset, resolve the conflicts, and then reshelve the changes to try again
When a shelveset is rejected it is reshelved using the same name prefixed with 'REJECTED-' under the build user's account. This is due to limitations of TFS (shelvesets cannot be renamed and cannot be shelved under a different user's account), so when a user wants to unshelve their rejected changes they will need to search for their shelveset under the build user's account
Revoke check in access to the build type files from everyone (including the build user) and only make changes to it manually at quiet times

Please post any bugs, questions or suggestions on the support forum

Source

The source code for OpenGauntlet is available zippped in the file below:

OpenGauntlet 1.4.6 Source Code

Please do not redistribute or publish any part or whole of the source code without first seeking my permission. Note that you will need Microsoft Visual Studio Team Edition for Database Professionals installed in order to open the database project (trial available). The individual files that make up the database can still be opened manually.

Please note: OpenGauntlet is not developed, endorsed, or supported by Microsoft. This is a freeware application that uses a Microsoft product, and any queries or suggestions should be posted on this site. In other words, don't bug Microsoft if I've done something wrong!