jetbrains.buildServer.configs.kotlin.v2018_1

Package jetbrains.buildServer.configs.kotlin.v2018_1

Defines the settings DSL for TeamCity 2018.1+

Most of the classes in the DSL correspond to the entities in TeamCity administration UI. The main classes are:

This DSL API version introduces a concept of portable DSL scripts which can be reused on the same or different TeamCity server. The basic idea is that all identifiers in DSL are relative to the project where the versioned settings are defined. During DSL execution TeamCity provides a context from which full identifiers are built. The context is relative if DSL was generated with the 'Generate portable DSL scripts' option enabled, otherwise it is absolute.

A pipeline: Compile -> Tests in 3 environments -> Deploy in portable DSL might look like this:

project {
    val compile = buildType {
        id("Compile")
        name = "Compile"
    }

    val tests = subProject {
        id("Tests")
        name = "Tests"

        for (OS in arrayListOf("Windows", "Linux", "MacOS")) {
            buildType {
                id("Tests_$OS")
                name = OS
                dependencies {
                    snapshot(compile) {
                    }
                }
            }
        }
    }

    buildType {
        id("Deploy")
        name = "Deploy"

        dependencies {
            for (test in tests.buildTypes) {
                snapshot(test) {
                }
            }
        }
    }
}

In order to support portable scripts the type of the id property was changed from String to Id. There are 2 types of ids: AbsoluteId which is used as is, and RelativeId to which TeamCity prepends an id of the project where versioned settings are defined. For example, the relative id Build in a project with id Product_V1 is expanded to Product_V1_Build during DSL execution. Relative ids can be used only in relative context, absolute ids can be used in both absolute or relative contexts. If you define an entity with an absolute id in a relative context, the DSL becomes non-portable: e.g. it cannot be reused in a different project on the same TeamCity server due to id clash.

TeamCity provides a set of predefined build parameters which can be referenced e.g. in build scripts. Dependency and VCS root parameters contain ids of the corresponding entities. In DSL you can write such references using the depParamRefs, reverseDepParamRefs, and paramRefs properties. Let's say you have a build listing branch revisions in the remote repository, it might look like this:

buildType {
    vcs {
        root(SourceGit) //SourcesGit is a Git VCS root with the id 'Project1_Tests_SourceGit'
    }
    steps {
        script {
            scriptContent = """
                git ls-remote %vcsroot.Project1_Tests_SourceGit.url%
            """.trimIndent()
        }
    }
}

On the build agent the %vcsroot.Project1_Tests_SourceGit.url% will be replaced with the a real url of the VCS root. Using the new API script content can be rewritten as:

scriptContent = """
    git ls-remote ${SourceGit.paramRefs["url"]}
""".trimIndent()

Migrating from previous DSL API versions

In order to migrate you need to update the imported DSL API package to jetbrains.buildServer.configs.kotlin.v2018_1 and to specify the id if the correct type. For example:

import jetbrains.buildServer.configs.kotlin.v2017_2.*

object LinuxTests : BuildType({
    id = "Tests_Linux"
    ...
})

should be changed to

import jetbrains.buildServer.configs.kotlin.v2018_1.*

object LinuxTests : BuildType({
    id = AbsoluteId("Tests_Linux")
    ...
})

or you can use the id() function which accepts Strings and selects an id type based on the context in which DSL is executed:

import jetbrains.buildServer.configs.kotlin.v2018_1.*

object LinuxTests : BuildType({
    id("Tests_Linux")
    ...
})

Types

AbsoluteId

data class AbsoluteId : Id

Entity id to be used as is, without any prefixes provided by TeamCity.

ArtifactDependency

class ArtifactDependency

TeamCity artifact dependency.

ArtifactRule

data class ArtifactRule

A rule specifying how to copy artifacts from dependency. Use methods of the companion object to create it.

BuildFeature

open class BuildFeature : Parametrized, Validatable

Represents TeamCity build feature

BuildFeatures

class BuildFeatures : Validatable

Collection of build features in build configuration or template

BuildRule

data class BuildRule

A rule matching a build, use one of the methods in ArtifactDependency class to create it

BuildStep

open class BuildStep : Parametrized, Validatable

Represents TeamCity Build Step

BuildSteps

class BuildSteps : Validatable

Collection of build steps in build configuration or template

BuildType

open class BuildType : BuildTypeSettings, Validatable

Represents TeamCity build configuration.

BuildTypeRefs

open class BuildTypeRefs

Provides methods for creating references to buildType parameters

BuildTypeSettings

open class BuildTypeSettings : Validatable, IdOwner

Contains common settings between BuildType and Template

CheckoutMode

enum class CheckoutMode

VCS checkout mode, specifies how sources are transferred to the build agent

Cleanup

class Cleanup

Specifies clean-up rules for project, build configuration, or template

CleanupLevel

enum class CleanupLevel

Specifies what data should be cleaned. Each level includes the one(s) above it.

CleanupRule

data class CleanupRule

Clean-up rule, use one of the methods in Cleanup to create it

CompoundDelegateProvider

class CompoundDelegateProvider<T : CompoundParam<T>>

CompoundParam

abstract class CompoundParam<V> : Parametrized

CompoundParamDelegate

class CompoundParamDelegate<T : CompoundParam<T>> : ParameterDelegate<T>

Consumer

class Consumer : ErrorConsumer

Dependencies

class Dependencies

Collection of dependencies in build configuration or template

Dependency

class Dependency

Represents dependency of one build on another

DslContext

object DslContext

Context of DSL execution

ErrorConsumer

interface ErrorConsumer

Consumes validation errors

FailureAction

enum class FailureAction

Action in case of snapshot dependency failure.

FailureCondition

open class FailureCondition : BuildFeature

TeamCity failure condition

FailureConditions

class FailureConditions : Validatable

Collection of failure conditions in build configuration or template

Id

sealed class Id : IdOwner

An id of a TeamCity entity. It appears in the web UI and is used in urls. If the entity has a uuid specified, then the id can be changed at any time. If uuid is omitted, then TeamCity treats an entity with a changed id as a new entity, all data associated with the old entity will be lost (e.g. a build history, a commit graph).

IdGenerator

class IdGenerator

IdOwner

interface IdOwner

IdeaDuplicates

class IdeaDuplicates : IdeaSettingsBasedRunner

IdeaInspections

class IdeaInspections : IdeaSettingsBasedRunner

IdeaRunner

class IdeaRunner : IdeaSettingsBasedRunner

IdeaSettingsBasedRunner

abstract class IdeaSettingsBasedRunner : BuildStep

Options

class Options : Parametrized

Parameter

data class Parameter

Build parameter

ParameterDelegate

abstract class ParameterDelegate<T>

ParameterDisplay

enum class ParameterDisplay

Specifies how parameter is shown in the Run Custom Build dialog

ParameterRef

class ParameterRef

Reference to a parameter

ParameterSpec

sealed class ParameterSpec

Parameter specification

ParameterSpecCheckbox

class ParameterSpecCheckbox : ParameterSpec

ParameterSpecFreeForm

class ParameterSpecFreeForm : ParameterSpec

ParameterSpecPassword

class ParameterSpecPassword : ParameterSpec

ParameterSpecRegex

class ParameterSpecRegex : ParameterSpec

ParameterSpecSelect

class ParameterSpecSelect : ParameterSpec

ParameterSpecText

class ParameterSpecText : ParameterSpec

Parametrized

open class Parametrized

ParametrizedWithType

open class ParametrizedWithType : Parametrized

Allows to add parameters to project, build configuration, or template

Project

open class Project : Validatable, IdOwner

Represents TeamCity project.

ProjectFeature

open class ProjectFeature : Parametrized, Validatable

Represents project-level feature

ProjectFeatures

class ProjectFeatures : Validatable

Collection of features in a project

RelativeId

data class RelativeId : Id

Entity id relative to the project where versioned settings were enabled. When DSL executed the id of the project with enabled versioned settings is prepended to all relative ids. Can be used only in DSL generated with the 'Generate portable DSL scripts' option enabled.

Requirement

data class Requirement

An agent requirement, use methods in Requirements class to create it

RequirementType

enum class RequirementType

Requirements

class Requirements

Collection of agent requirements in build configuration or template

ReuseBuilds

enum class ReuseBuilds

Reuse builds mode for snapshot dependencies

SingleDelegateProvider

class SingleDelegateProvider<T>

SingleParamDelegate

class SingleParamDelegate<T> : ParameterDelegate<T>

SnapshotDependency

class SnapshotDependency

TeamCity snapshot dependency

Template

open class Template : BuildTypeSettings, Validatable

Represents TeamCity build template.

Trigger

open class Trigger : Parametrized, Validatable

TeamCity build trigger

Triggers

class Triggers : Validatable

Collection of build triggers in build configuration or template

Validatable

interface Validatable

VcsRoot

open class VcsRoot : Parametrized, Validatable, IdOwner

A base class representing TeamCity VCS root.

VcsRootEntry

data class VcsRootEntry

VcsRootRefs

open class VcsRootRefs

Provides methods for creating references to VCS related properties

VcsSettings

class VcsSettings

Contains settings from the Version Control Settings tab of build configuration or template.

_Samples

class _Samples

Annotations

TeamCityDsl

annotation class TeamCityDsl

Extensions for External Classes

kotlin.String

Properties

ID_GENERATORS_FOR_TEMPLATES

val ID_GENERATORS_FOR_TEMPLATES: <ERROR CLASS>

TQ

val TQ: String

Used to escape triple quotes inside multi-line strings

checkMissingUuids

var checkMissingUuids: Boolean

Specifies whether a missing uuid should cause a validation error. If set to false (default) an omitted uuid is allowed and is later reconstructed by id of the entity.

version

var version: String?

Version of TeamCity in which kotlin code was generated.

Functions

copy

fun <T : VcsRoot> T.copy(): T

Copies the receiver VCS root.

fun <T : VcsRoot> T.copy(block: T.() -> Unit): T

Copies the receiver VCS root and initialize it with the specified block.

fun ArtifactDependency.copy(): ArtifactDependency

Copies the receiver artifact dependency

fun SnapshotDependency.copy(): SnapshotDependency

Copies the receiver snapshot dependency

fun Dependency.copy(): Dependency

Copies the receiver dependency

fun BuildSteps.copy(): BuildSteps

Copies the receiver build steps

fun Cleanup.copy(): Cleanup

Copies the receiver cleanup

fun FailureConditions.copy(): FailureConditions

Copies the receiver failure conditions

fun VcsSettings.copy(): VcsSettings

Copies the receiver vcs settings

fun Triggers.copy(): Triggers

Copies the receiver triggers

fun Requirements.copy(): Requirements

Copies the receiver requirements

fun Dependencies.copy(): Dependencies

Copies the receiver dependencies

fun BuildFeatures.copy(): BuildFeatures

Copies the receiver build features

fun ProjectFeatures.copy(): ProjectFeatures

Copies the receiver project features

copySettingsTo

fun <T : BuildTypeSettings> T.copySettingsTo(target: T): T

Copies the receiver build settings to the specified target

copyTo

fun <T : VcsRoot> T.copyTo(target: T): T

Copies the receiver VCS root to the specified target VCS root

fun BuildSteps.copyTo(target: BuildSteps): BuildSteps

Copies the receiver build steps to the specified target

fun Cleanup.copyTo(target: Cleanup): Cleanup

Copies the receiver cleanup to the specified target

fun FailureConditions.copyTo(target: FailureConditions): FailureConditions

Copies the receiver failure conditions to the specified target

fun VcsSettings.copyTo(target: VcsSettings): VcsSettings

Copies the receiver vcs settings to the specified target

fun Triggers.copyTo(target: Triggers): Triggers

Copies the receiver triggers to the specified target

fun Requirements.copyTo(target: Requirements): Requirements

Copies the receiver requirements to the specified target

fun Dependencies.copyTo(target: Dependencies): Dependencies

Copies the receiver dependencies to the specified target

fun BuildFeatures.copyTo(target: BuildFeatures): BuildFeatures

Copies the receiver build features to the specified target

fun ProjectFeatures.copyTo(target: ProjectFeatures): ProjectFeatures

Copies the receiver project features to the specified target

ideaDuplicates

fun BuildSteps.ideaDuplicates(init: IdeaDuplicates.() -> Unit = {}): Unit

ideaInspections

fun BuildSteps.ideaInspections(init: IdeaInspections.() -> Unit = {}): Unit

ideaRunner

fun BuildSteps.ideaRunner(init: IdeaRunner.() -> Unit = {}): Unit

prepareRelativeProject

fun prepareRelativeProject(project: Project): Unit

project

fun project(project: Project): Unit
fun project(init: Project.() -> Unit): Unit

Defines TeamCity project

relativeIdCannotBeUsed

fun relativeIdCannotBeUsed(description: String, id: Id?): String

relativeIdInAbsoluteHierarchy

fun relativeIdInAbsoluteHierarchy(id: Id?): Boolean

reportRelativeIds

fun reportRelativeIds(project: Project): Unit
fun reportRelativeIds(project: Project, rootProject: Boolean): Unit

runPrivileged

fun <T> runPrivileged(function: () -> T): T