TeamCity

Running on TeamCity will automatically enable custom theming for your build log output including collapsible blocks for better structuring:

info

Please refer to the official TeamCity documentation for questions not covered here.

Environment Variables

You can access predefined parameters by using the TeamCity class:

TeamCity TeamCity => TeamCity.Instance;

Target Print => _ => _
    .Executes(() =>
    {
        Log.Information("Branch = {Branch}", TeamCity.BranchName);
        Log.Information("Commit = {Commit}", TeamCity.BuildVcsNumber);
    });

Exhaustive list of strongly-typed properties

class TeamCity
{
    string                              AuthPassword            { get; }
    string                              AuthUserId              { get; }
    string                              BranchName              { get; }
    string                              BuildConfiguration      { get; }
    long                                BuildId                 { get; }
    string                              BuildNumber             { get; }
    string                              BuildTypeId             { get; }
    string                              BuildVcsNumber          { get; }
    IReadOnlyDictionary<string, string> ConfigurationProperties { get; }
    bool                                IsBuildPersonal         { get; }
    bool                                IsPullRequest           { get; }
    string                              ProjectId               { get; }
    string                              ProjectName             { get; }
    long?                               PullRequestNumber       { get; }
    string                              PullRequestSourceBranch { get; }
    string                              PullRequestTargetBranch { get; }
    string                              PullRequestTitle        { get; }
    IReadOnlyCollection<string>         RecentlyFailedTests     { get; }
    IReadOnlyDictionary<string, string> RunnerProperties        { get; }
    string                              ServerUrl               { get; }
    IReadOnlyDictionary<string, string> SystemProperties        { get; }
    string                              Version                 { get; }
}

Configuration Generation

You can generate build configuration files from your existing target definitions by adding the TeamCity attribute. For instance, you can run the Compile target on every push with the latest Ubuntu image:

Build.cs

[TeamCity(
    VcsTriggeredTargets = new[] { nameof(Compile) })]
class Build : NukeBuild { /* ... */ }

Generated output

.teamcity/settings.kts

project {
    buildType(Compile)
}

object Compile : BuildType({
    name = "Compile"
    vcs {
        root(DslContext.settingsRoot)
        cleanCheckout = true
    }
    steps {
        exec {
            path = "build.cmd"
            arguments = "Compile"
            conditions { contains("teamcity.agent.jvm.os.name", "Windows") }
        }
        exec {
            path = "build.sh"
            arguments = "Compile"
            conditions { doesNotContain("teamcity.agent.jvm.os.name", "Windows") }
        }
    }
    params {
        text(
            "teamcity.ui.runButton.caption",
            "Compile",
            display = ParameterDisplay.HIDDEN)
    }
    triggers {
        vcs {
            triggerRules = "+:**"
        }
    }
})

info

Whenever you make changes to the attribute, you have to run the build at least once to regenerate the pipelines file.

Artifacts

If your targets produce artifacts, like packages or coverage reports, you can publish those directly from the target definition:

Target Pack => _ => _
    .Produces(PackagesDirectory / "*.nupkg")
    .Executes(() => { /* Implementation */ });

Generated output

.teamcity/settings.kts

object Pack : BuildType({
    artifactRules = "output/packages/*.nupkg => output/packages"
}

After your build has finished, those artifacts will be listed under the artifacts tab:

Importing Secrets

If you want to use secret variables from your TeamCity project, you can use the ImportSecrets property and TeamCityToken attribute to automatically load them into a secret parameter defined in your build:

Build.cs

[TeamCity(
    // ...
    ImportSecrets = new[] { nameof(NuGetApiKey) })]
[TeamCityToken(nameof(NuGetApiKey), "<guid>")]
class Build : NukeBuild
{
    [Parameter] [Secret] readonly string NuGetApiKey;
}

Generated output

.teamcity/settings.kts

project {
    params {
        password (
            "env.NuGetApiKey",
            label = "NuGetApiKey",
            value = "credentialsJSON:<guid>",
            display = ParameterDisplay.HIDDEN)
    }
}

note

If you're facing any issues, make sure that the name in the TeamCity settings is the same as generated into the pipelines file.

Using Credentials

For every build run, TeamCity generates a pair of one-time credentials that you can use to authenticate with the TeamCity API:

Build.cs

class Build : NukeBuild
{
    TeamCity TeamCity => TeamCity.Instance;

    Target Request => _ => _
        .Executes(() =>
        {
            Log.Information("UserId = {UserId}", TeamCity.AuthUserId);
            Log.Information("Password = {Password}", TeamCity.AuthPassword);
        });
}