VCS post-commit hook

1. In VSTS Project Settings, go to the Service Hooks tab
2. Click '+' to add a new service hook
3. Select Web Hooks
4. In Trigger on this type of event, select Code pushed
5. Optionally, review the Filters and just check the Repository (and branch) that should trigger the event.
6. In the URL, enter something like https://www.example.com/app/rest/vcs-root-instances/commitHookNotification?locator=vcsRoot:(type:jetbrains.git,count:99999),property:(name:url,value:%2Fbuildname,matchType:contains),count:99999
   the locator can vary depending on your individual requirements
7. Enter the username and password to authenticate with TeamCity
8. Set Resource details to send, Messages to send and Detailed messages to send to None
9. Click Test to confirm that everything works.

VSTS

1. Go to the Service Hooks tab for your project
2. Click on the + icon
3. Choose Web Hooks and click Next
4. Select Pull request created.
   
5. If appropriate, select a specific repository and click Next
6. In URL, enter the URL that VSTS will use to connect to the pull request server, including a query string that defines which TeamCity build should be queued.
   Eg. If the pull request server is hosted at https://www.example.com/pullrequestserver and the TeamCity build type id is My_CI_Build then you’d use https://www.example.com/pullrequestserver?buildTypeId=My_CI_Build
7. In Username and Password, enter the credentials that will be used to authenticate with TeamCity
8. Leave Resource details to send as All.
9. Set Messages to send and Detailed messages to send to None
10. Click on Test to try it out.
11. Click on Finish to save this service hook.
12. Repeat these steps to create another service hook for Pull request updated, also setting the Change filter to Source branch updated.

Branch policies.

TeamCity

1. Click on add build Webhooks, then Click to create new WebHook for this build and add a new web hook for the project
2. In the URL, enter the URL that TeamCity will use to connect to the pull request server.
   Eg. If the pull request server is hosted at https://www.example.com/pullrequestserver, you would use https://www.example.com/pullrequestserver/buildComplete.
3. Set the payload format to Legacy webhook (JSON)
4. Clear all the trigger events except On Completion Trigger when build successful and Trigger when build fails
5. Click Save

+:refs/heads/(master)
+:refs/pull/*/merge

Part 2 in a series on integrating VSTS with TeamCity

This is a web service that handles web hook messages triggered by events in VSTS and TeamCity.

I started by using the sample Create a pull request status server with Node.js. As the title suggests, this is a Node application and it uses the Express library to run as a web server. I’d never written a Node app before, but it turns out it is surprisingly easy. If you’re starting from scratch, I’d recommend following the sample tutorial first, so you get up to speed with creating a really simple Node app that VSTS can talk to. Once you’ve got that working, then you should be well placed to use the code samples below.

There’s really two main processes we need to support:

1. VSTS – Pull Request Created or Updated → Trigger TeamCity build of branch</li>
2. TeamCity build complete → Tell VSTS if build was success or failure</li>

It’s also worth highlighting a couple of design goals for the pull request server:

• Avoid hard-coding any specific details in the script, so that it could be easily reused in other repositories. As such, specific details (user credentials, TeamCity build configuration names etc) are configured as extra parameters in the web hook / service hook calls.
• Be stateless

NPM packages

 "dependencies": {
    "basic-auth": "^2.0.0",
    "body-parser": "^1.18.2",
    "express": "^4.16.2",
    "teamcity-rest-api": "0.0.8",
    "vso-node-api": "^6.2.8-preview"
  },
  "devDependencies": {
    "@types/basic-auth": "^1.1.2",
    "@types/body-parser": "^1.16.8",
    "@types/express": "^4.0.39",
    "@types/node": "^8.5.1",
    "nodemon": "^1.13.3",
    "ts-node": "^4.0.2",
    "tslint": "^5.8.0",
    "typescript": "^2.6.2"
  }

Note that the following code snippets have been ‘tidied’ for the blog post - the original has a fair bit of file and console logging which is invaluable when diagnosing what’s going on as you’re modifying the logic. I also switched to using TypeScript as I really appreciated the type checking it provides.

Get things ready

import * as auth from 'basic-auth';
import * as bodyParser from 'body-parser';
import * as express from 'express';
import * as fs from 'fs';
import * as vsts from 'vso-node-api';
import { GitPullRequestStatus, GitStatusState } from 'vso-node-api/interfaces/GitInterfaces';

const teamcity = require('teamcity-rest-api');

const app = express();
app.use(bodyParser.json({ limit: '5mb'}));

const collectionURL = process.env.COLLECTIONURL;
const token = process.env.VSTSTOKEN;

const authHandler = vsts.getPersonalAccessTokenHandler(token!);
const connection = new vsts.WebApi(collectionURL!, authHandler);

const vstsGit = connection.getGitApi();

Handling a pull request event

app.post('/prserver', (req, res) => {
    const user = auth(req);

    const buildTypeId = req.query.buildTypeId;

    if (!buildTypeId || !user) {
        res.sendStatus(400);
        return;
    }

    const mergeStatus = req.body.resource.mergeStatus;

    if (mergeStatus !== 'succeeded') {
        return;
    }

    // Get the details about the PR from the service hook payload
    const repoId = req.body.resource.repository.id;
    const pullRequestId = req.body.resource.pullRequestId;
    const commitId = req.body.resource.lastMergeSourceCommit.commitId;

    // This needs to match the branch pattern in TeamCity
    const branchName = pullRequestId;

    // We need to find out the pull request IterationId
    vstsGit.getPullRequestIterations(repoId, pullRequestId, undefined, false)
    .then((iterations: any[]) => {
        return iterations.filter(item => item.sourceRefCommit.commitId === commitId)[0].id;
    })
    .then((iterationId: string) => {

        // trigger TeamCity build
        const client = teamcity.create({
            url: 'http://localhost:8111',
            username: user.name,
            password: user.pass
        });

        // This is the data we are posting to TeamCity
        // tslint:disable-next-line:max-line-length
        const buildNodeObject = `<build branchName='${branchName}'><buildType id='${buildTypeId}' /><properties><property name='vsts.pullRequestId' value="${pullRequestId}" inherited="false"/><property name='vsts.repositoryId' value="${repoId}" inherited="false"/><property name='vsts.iterationId' value="${iterationId}" inherited="false"/></properties></build>`;

        client.builds.startBuild(buildNodeObject)
            .then((buildStatus: any) => {
                // Build the status object that we want to post.
                // Assume that the PR is ready for review...
                const prStatus = {
                    'iterationId': iterationId,
                    'state': 'pending',
                    'description': `Queued build: ${buildStatus.buildTypeId}`,
                    'targetUrl': buildStatus.webUrl,
                    'context': {
                        'name': 'teamcity',
                        'genre': 'continuous-integration'
                    },
                    _links: null
                };

                // Post the status to the PR
                vstsGit.createPullRequestStatus(prStatus as any, repoId, pullRequestId);
            }, (reason: any) => {
                // error logging
            });
    }).catch((reason: any) => {
        // error logging
    });

    res.send('Received the POST');
});

Handling build completion from TeamCity

app.post('/prserver/buildComplete', (req, res) => {
    const pullRequestIdNode = req.body.build.teamcityProperties.find((item: any) => item.name === 'vsts.pullRequestId');

    if (!pullRequestIdNode) {
        // ignore if we don't have expected property
        return;
    }

    const pullRequestId = pullRequestIdNode.value;

    const repositoryId = req.body.build.teamcityProperties.filter((item: any) => item.name === 'vsts.repositoryId')[0].value;
    const iterationId = req.body.build.teamcityProperties.filter((item: any) => item.name === 'vsts.iterationId')[0].value as number;

    const prStatus = {
        iterationId: iterationId,
        state: GitStatusState.Succeeded,
        'description': 'Build succeeded',
        'targetUrl': req.body.build.buildStatusUrl,
        'context': {
            'name': 'teamcity',
            'genre': 'continuous-integration'
        },
        _links: null
    };

    if (req.body.build.buildResult !== 'success') {
        prStatus.state = GitStatusState.Failed; // 'failed';
        prStatus.description = `Build result: ${req.body.build.buildResult}`;
    }

    // Post the status to the PR
    vstsGit.createPullRequestStatus(prStatus as any, repositoryId, pullRequestId);

});

During development I ran the Node app from the command-line and made extensive use of console and file logging.

Once I was satisfied it was working as expected, I switched to using iisnode to run it under IIS.

Where this app runs depends on how accessible your TeamCity server is. If TeamCity is Internet-facing then the server could run anywhere (maybe even as something like an Azure Function). If TeamCity is running behind your firewall, then you might choose to host the pull server internally too. Note that VSTS does need to be able to contact the pull server – either directly (so the pull server itself is Internet-facing), or using a reverse proxy service like ngrok.

In the next post, I’ll describe how to configure TeamCity and VSTS to call the pull request server.

• Require a minimum number of reviewers
• Check for linked work items
• Check for comment resolution
• Enforce a merge strategy
• Build validation
• Approval from external services

• Introduction
• Creating the pull request server
• Configuration
• Wrapping up

(I) use ‘test fixture’ or just ‘fixture’ to mean ‘the pre-conditions of the test’ and Testcase class to mean ‘the class that contains the Test Methods and any code needed to set up the test fixture’. (xUnit Test Patterns p.59)

Cake.NuGet.Tests project structure

[Fact]
public void Should_Be_Able_To_Install_If_Scheme_Is_Correct()
{
    // Given
    var fixture = new NuGetPackageInstallerFixture();
    fixture.Package = new PackageReference("nuget:?package=Cake.Core");

    // When
    var result = fixture.CanInstall();

    // Then
    Assert.True(result);
}

internal sealed class NuGetPackageInstallerFixture
{
    public ICakeEnvironment Environment { get; set; }
    public FakeFileSystem FileSystem { get; set; }
    public IProcessRunner ProcessRunner { get; set; }
    public INuGetToolResolver ToolResolver { get; set; }
    public INuGetContentResolver ContentResolver { get; set; }
    public ICakeLog Log { get; set; }

    public PackageReference Package { get; set; }
    public PackageType PackageType { get; set; }
    public DirectoryPath InstallPath { get; set; }

    public ICakeConfiguration Config { get; set; }

    public NuGetPackageInstallerFixture()
    {
        Environment = FakeEnvironment.CreateUnixEnvironment();
        FileSystem = new FakeFileSystem(Environment);
        ContentResolver = Substitute.For<INuGetContentResolver>();
        Log = Substitute.For<ICakeLog>();
        Config = Substitute.For<ICakeConfiguration>();

        ToolResolver = Substitute.For<INuGetToolResolver>();
        ToolResolver.ResolvePath().Returns(new FilePath("/Working/tools/nuget.exe"));

        Package = new PackageReference("nuget:https://myget.org/temp/?package=Cake.Foo&prerelease&version=1.2.3");
        PackageType = PackageType.Addin;
        InstallPath = new DirectoryPath("./nuget");

        ProcessRunner = Substitute.For<IProcessRunner>();
        ProcessRunner.When(p => p.Start(Arg.Any<FilePath>(), Arg.Any<ProcessSettings>()))
            .Do(info => FileSystem.CreateDirectory(InstallPath.Combine(Package.Package.ToLowerInvariant()).Combine(Package.Package)));
    }

    public void InstallPackageAtSpecifiedPath(DirectoryPath path)
    {
        ProcessRunner.When(p => p.Start(Arg.Any<FilePath>(), Arg.Any<ProcessSettings>()))
            .Do(info => FileSystem.CreateDirectory(path));
    }

    public NuGetPackageInstaller CreateInstaller()
    {
        return new NuGetPackageInstaller(FileSystem, Environment, ProcessRunner, ToolResolver, ContentResolver, Log, Config);
    }

    public IReadOnlyCollection<IFile> Install()
    {
        var installer = CreateInstaller();
        return installer.Install(Package, PackageType, InstallPath);
    }

    public bool CanInstall()
    {
        var installer = CreateInstaller();
        return installer.CanInstall(Package, PackageType);
    }
}