rodm / Gradle Teamcity Plugin

= Gradle TeamCity plugin :uri-teamcity-sdk-docs: https://plugins.jetbrains.com/docs/teamcity/ :uri-teamcity-environment: {uri-teamcity-sdk-docs}/development-environment.html :uri-server-descriptor: {uri-teamcity-sdk-docs}/plugins-packaging.html#PluginsPackaging-PluginDescriptor :uri-agent-descriptor: {uri-teamcity-sdk-docs}/plugins-packaging.html#PluginsPackaging-PluginDescriptor2 :uri-gradle-plugin-portal: https://plugins.gradle.org/ :uri-jetbrains-plugin-portal: https://plugins.jetbrains.com/teamcity :uri-github-project: https://github.com/rodm/gradle-teamcity-plugin/ :uri-jetbrains-hub-token: https://www.jetbrains.com/help/hub/Manage-Permanent-Tokens.html :uri-travis-project: https://travis-ci.org/rodm/gradle-teamcity-plugin :uri-travis-status: https://travis-ci.org/rodm/gradle-teamcity-plugin.svg?branch=master :uri-appveyor-project: https://ci.appveyor.com/project/rodm/gradle-teamcity-plugin :uri-appveyor-status: https://ci.appveyor.com/api/projects/status/github/rodm/gradle-teamcity-plugin?branch=master&svg=true :plugin-version: 1.1 :default-api-version: 9.0 :example-api-version: 2018.1

The plugin provides support for {uri-teamcity-sdk-docs}[developing TeamCity plugins], creating agent and server side archives, publishing them to {uri-jetbrains-plugin-portal}[plugins portal], downloading and installing a TeamCity server and tasks to deploy, start and stop the server and agent.

image:{uri-travis-status}["Build Status", link="{uri-travis-project}}"] image:{uri-appveyor-status}["Build Status", link="{uri-appveyor-project}"]

== Supported Gradle and Java versions

|=== |Plugin version |Gradle version |Java version |Documentation |v1.3 |5.0+ |Java 8 & later |{uri-github-project}/blob/v1.3/README.adoc#using-the-plugin[README] |v1.2 |4.0+ |Java 7 & later |{uri-github-project}/blob/v1.2.2/README.adoc#using-the-plugin[README] |v1.1 |3.0+ |Java 7 & 8 |{uri-github-project}/blob/v1.1/README.adoc#using-the-plugin[README] |v1.0 |2.8+ |Java 7 & 8 |{uri-github-project}/blob/v1.0/README.adoc#using-the-plugin[README] |===

== Building the plugin

To build the plugin and run the unit tests run

./gradlew -s check

To run the functional tests run

./gradlew -s functionalTest

To test the samples run

./gradlew -s samplesTest

== Using the plugin

=== Applying the plugins to a build

The plugin archive published to the {uri-gradle-plugin-portal}[Gradle Plugin Portal] contains four plugins:

• com.github.rodm.teamcity-server - Provides tasks to package a TeamCity plugin, deploy and undeploy the plugin to a TeamCity server, and tasks to start and stop the server and default agent.
• com.github.rodm.teamcity-agent - Provides tasks to package the Agent side of a TeamCity plugin.
• com.github.rodm.teamcity-common - Adds the common-api dependency to a project.
• com.github.rodm.teamcity-environments - Adds tasks to download, install, start and stop a TeamCity Server and Build Agent.

Refer to the Gradle Plugin Portal for instructions on how to apply the {uri-gradle-plugin-portal}plugin/com.github.rodm.teamcity-server[server], {uri-gradle-plugin-portal}plugin/com.github.rodm.teamcity-agent[agent], {uri-gradle-plugin-portal}plugin/com.github.rodm.teamcity-common[common] and {uri-gradle-plugin-portal}plugin/com.github.rodm.teamcity-environments[environments] plugins.

=== Configurations

The plugins add the following configurations.

• provided : The provided configuration is used to define dependencies required at compile time but not to be included in the plugin. By default the plugins add the agent-api and server-api dependencies when the java plugin is also applied.
• agent : The agent configuration is used to define additional dependencies to be included in the agent plugin lib directory when used with the agent plugin. When used with the server plugin the dependencies are added to the agent directory of the plugin archive.
• server : The server configuration is used to define additional dependencies to be included in the server plugin lib directory when used with the server plugin.
• plugin : The plugin configuration is used by the agent and server plugins to publish the agent and server plugin archives.

=== Extension Properties

The following properties are defined in the teamcity configuration block. The version property controls the version of the TeamCity API dependencies added to the provided configuration. The plugin descriptor can be specified as a path to a file or by a configuration block within the build script.

• version : The version of the TeamCity API to build against. Defaults to '{default-api-version}'.
• defaultRepositories : The defaultRepositories flag controls adding the default repositories to the build. By default Maven Central and the TeamCity repository, https://download.jetbrains.com/teamcity-repository, are configured for resolving dependencies. Setting this flag to false allows a local repository to be used for resolving dependencies.

=== TeamCity Server Plugin

The plugin when applied with the Java Plugin, adds the JetBrains Maven repository and adds the TeamCity server-api, server-web-api and tests-support dependencies to the provided and testImplementation configurations. If the Java Plugin is not applied the plugin provides only the tasks to package and publish the server side plugin archive if a plugin descriptor is defined.

The server plugin can be combined with the agent plugin in the same project but not with the Java Plugin.

==== Configuration

The following properties can be defined in the server configuration block.

• descriptor : The plugin descriptor, the descriptor can be defined within the build script or reference an external file.
• tokens : The tokens property is a map of tokens to be replaced in the descriptor file with values. This only applies if the descriptor is referencing an external file.
• files : The files property is a CopySpec that defines additional files to be included in the plugin archive.
• archiveName : The archiveName property defines the name of the plugin archive output by the serverPlugin task. Defaults to the name of the project and the project version.

The plugin descriptor properties shown in the examples below and described in the TeamCity documentation for {uri-server-descriptor}[Server-Side Plugin Descriptor]

==== Tasks

• serverPlugin : Builds and packages a TeamCity plugin. The task performs validation of the plugin descriptor and outputs a warning if a required value is missing.
• publishPlugin : Publishes a plugin to the {uri-jetbrains-plugin-portal}[JetBrains TeamCity Plugin Repository]
• generateDescriptor : If the descriptor is defined in the build script this task is enabled and will output the descriptor to the build directory.
• processDescriptor : If the descriptor is defined as an external file this task is enabled and will copy the file to the build directory. ('build/descriptor/server')

The plugin enhances the jar task to perform validation of the bean definition file and outputs a warning if there are no beans defined or if a class is missing from the jar file.

==== Examples

Plugin descriptor defined in the build script.

[source,groovy] [subs="attributes"]

teamcity {
    // Use TeamCity {example-api-version} API
    version = '{example-api-version}'

    // Plugin descriptor
    server {
        descriptor {
            // required properties
            name = project.name
            displayName = 'TeamCity Plugin'
            version = project.version
            vendorName = 'vendor name'

            // optional properties
            description = 'Example TeamCity plugin'
            downloadUrl = 'download url'
            email = '[email protected]'
            vendorUrl = 'vendor url'
            vendorLogo = 'vendor logo'

            // deployment properties
            useSeparateClassloader = true
            allowRuntimeReload = true
            nodeResponsibilitiesAware = true

            // requirements properties
            minimumBuild = '10'
            maximumBuild = '20'

            parameters {
                parameter 'name1', 'value1'
                parameter 'name2', 'value2'
            }

            dependencies {
                plugin 'plugin1-name'
                plugin 'plugin2-name'
                tool 'tool1-name'
                tool 'tool2-name'
            }
        }

        // Additional files can be included in the server plugin archive using the files configuration block
        files {
            into('tooldir') {
                from('tooldir')
            }
        }
    }
}

Plugin descriptor defined in an external file at the root of the project. A map of tokens to be replaced in the descriptor file can be provided using the tokens property.

[source,groovy] [subs="attributes"]

teamcity {
    // Use TeamCity {example-api-version} API
    version = '{example-api-version}'

    server {
        // Locate the plugin descriptor in the root directory of the project
        descriptor = file('teamcity-plugin.xml')
        tokens = [VERSION: project.version, VENDOR_NAME: 'vendor name']
    }
}

The following example uses the Kotlin DSL.

[source,groovy] [subs="attributes"] .build.gradle.kts

teamcity {
    version = "{example-api-version}"

    server {
        descriptor {
            // required properties
            name = project.name
            displayName = "TeamCity Plugin"
            version = project.version as String?
            vendorName = "vendor name"

            // optional properties
            description = "Example TeamCity plugin"
            downloadUrl = "download url"
            email = "[email protected]"
            vendorUrl = "vendor url"
            vendorLogo = "vendor logo"

            // deployment properties
            useSeparateClassloader = true
            allowRuntimeReload = true
            nodeResponsibilitiesAware = true

            // requirements properties
            minimumBuild = "10"
            maximumBuild = "20"

            parameters {
                parameter("name1", "value1")
                parameter("name2", "value2")
            }

            dependencies {
                plugin("plugin1-name")
                plugin("plugin2-name")
                tool("tool1-name")
                tool("tool2-name")
            }
        }

        files {
            into("tooldir") {
                from("tooldir")
            }
        }
    }
}

==== Publishing a plugin

The publishPlugin task is used to upload the plugin archive to the {uri-jetbrains-plugin-portal}[JetBrains TeamCity Plugin Repository]. Before publishing a plugin you will need to create a JetBrains Account, follow the 'Sign In' link at the top of the plugin repository page. The publishPlugin task cannot be used to publish new plugins, the first upload must be completed using the Upload plugin link on the plugin repository website.

The publishPlugin task requires a {uri-jetbrains-hub-token}[JetBrains Hub token] to publish a plugin to the repository as shown in the following examples.

The following example configures the publish task.

[source,groovy] [subs="attributes"] .build.gradle

publishPlugin { token = findProperty('jetbrains.token') }

The following example uses the Kotlin DSL.

[source,groovy] .build.gradle.kts

tasks.withType { token = findProperty("jetbrains.token") as String? }

The token and other properties can also be configured in the publish section of the server configuration as shown in the following example. Optionally one or more channels can be specified using the channels property, by default the plugin is published to the 'Stable' channel. An optional notes property can be set to describe the changes made to the version of the plugin to be uploaded. The change or update notes text is shown on the plugin repository next to each plugin version.

[source,groovy] .build.gradle

teamcity { server { descriptor { ... } publish { channels = ['Beta'] token = findProperty('jetbrains.token') notes = 'change notes' } } }

It is recommended to store the credentials for the JetBrains Plugin Repository in $HOME/.gradle/gradle.properties.

=== TeamCity Agent Plugin

The plugin when applied with the Java Plugin, adds the JetBrains Maven repository and adds the TeamCity agent-api and tests-support dependencies to the provided and testImplementation configurations. If the Java Plugin is not applied the plugin provides only the tasks to package the agent side plugin archive if a plugin descriptor is defined.

==== Configuration

The following properties can be defined in the agent configuration block.

• descriptor : The plugin descriptor, the descriptor can be defined within the build script or reference an external file.
• tokens : The tokens property is a map of tokens to be replaced in the descriptor file with values. This only applies if the descriptor is referencing an external file.
• files : The files property is a CopySpec that defines additional files to be included in the plugin archive.
• archiveName : The archiveName property defines the name of the plugin archive output by the agentPlugin task. Defaults to the name of the project, if the teamcity-agent plugin and teamcity-server plugin are applied to the same project the agent plugin archive is appended with '-agent' and the project version.

The plugin descriptor properties are shown in the examples below and described in the TeamCity documentation for {uri-agent-descriptor}[Agent-Side Plugin Descriptor]

==== Tasks

• agentPlugin : Builds and packages the agent side of a TeamCity plugin. The artifacts defined on the 'agent' configuration are added to the lib directory of the agent plugin archive. The task performs validation of the plugin descriptor and outputs a warning if a required value is missing.
• generateAgentDescriptor : If the descriptor is defined in the build script this task is enabled and will output the descriptor to the build directory.
• processAgentDescriptor : If the descriptor is defined as an external file this task will copy the file to the build directory. ('build/descriptor/agent')

The plugin enhances the jar task to perform validation of the bean definition file and outputs a warning if there are no beans defined or if a class is missing from the jar file.

==== Examples

Agent side plugin descriptor

[source,groovy] [subs="attributes"]

teamcity {
    version = teamcityVersion

    agent {
        descriptor {
            pluginDeployment {
                useSeparateClassloader = false
                executableFiles {
                    include 'file1'
                    include 'file2'
                }
            }
            dependencies {
                plugin 'plugin-name'
                tool 'tool-name'
            }
        }
    }
}

Agent tool descriptor

[source,groovy] [subs="attributes"]

teamcity {
    version = teamcityVersion

    agent {
        descriptor {
            toolDeployment {
                executableFiles {
                    include 'tooldir/file1'
                    include 'tooldir/file2'
                }
            }
            dependencies {
                plugin 'plugin-name'
                tool 'tool-name'
            }
        }

        // Additional files can be included in the agent plugin archive using the files configuration block
        files {
            into('tooldir') {
                from('tooldir')
            }
        }
    }
}

The following example uses the Kotlin DSL.

[source,groovy] [subs="attributes"] .build.gradle.kts

extra["teamcityVersion"] = findProperty("teamcity.version") ?: "{example-api-version}"

teamcity {
    version = extra["teamcityVersion"] as String

    agent {
        descriptor {
            pluginDeployment {
                useSeparateClassloader = false
                executableFiles {
                    include("file1")
                    include("file2")
                }
            }
            dependencies {
                plugin("plugin-name")
                tool("tool-name")
            }
        }

        files {
            into("tooldir") {
                from("tooldir")
            }
        }
    }
}

=== TeamCity Environments Plugin

Applying this plugin provides tasks to download, install, start and stop a TeamCity Server and Build Agent. This allows a plugin to be debugged or tested against multiple versions of TeamCity.

==== Configuration

The environments configuration is available by applying the com.github.rodm.teamcity-environments plugin.

The following properties can be defined in the environments configuration block.

• downloadsDir : The directory the TeamCity installers are downloaded to. Defaults to downloads
• baseDownloadUrl : The base URL used to download the TeamCity installer. Defaults to https://download.jetbrains.com/teamcity.
• baseHomeDir : The base directory for a TeamCity install. Defaults to servers.
• baseDataDir : The base directory for a TeamCity Data directory. Defaults to data.

The following Gradle properties can be used to override the shared environment properties from the command line or by setting a value in a gradle.properties file.

• teamcity.environments.downloadsDir
• teamcity.environments.baseDownloadUrl
• teamcity.environments.baseDataDir
• teamcity.environments.baseHomeDir

Within the environments configuration block multiple TeamCity environments can be defined, each environment supports the following properties

• version : The TeamCity version, the version of TeamCity to download and install locally. Defaults to '{default-api-version}'.
• downloadUrl : The URL used to download the TeamCity installer. Defaults to ${baseDownloadUrl}/TeamCity-${version}.tar.gz.
• homeDir : The path to a TeamCity install. Defaults to ${baseHomeDir}/TeamCity-${version}
• dataDir : The path to the TeamCity Data directory. Defaults to ${baseDataDir}/${version}, version excludes the bug fix digit.
• javaHome : The path to the version of Java used to run the server and build agent. Defaults to the Java used to run Gradle.
• serverOptions : Options passed to the TeamCity server via the TEAMCITY_SERVER_OPTS environment variable. Default '-Dteamcity.development.mode=true -Dteamcity.development.shadowCopyClasses=true' these plugin development settings are described on the {uri-teamcity-environment}[Development Environment] page.
• agentOptions : Options passed to the TeamCity agent via the TEAMCITY_AGENT_OPTS environment variable.
• plugins : The collection of plugins to be deployed to the TeamCity server for this environment. Defaults to the plugin output by the serverPlugin task when the com.github.rodm.teamcity-server plugin is also applied.

==== Tasks

For each environment the following tasks are created based on the environment name:

• deployTo<environment> : Deploys one or more plugin archives to the TeamCity server for the environment, requires the environment dataDir property. If the environment is using TeamCity version 2018.2 or later and the server is running, the deploy task will send unload and load requests to the server. This allows changes to be made to the plugin without having to restart the server. Note that this feature currently relies on the file name of the plugin not changing between deploys.
• undeployFrom<environment> : Un-deploys one or more plugin archives from the TeamCity server for the environment, requires the environment dataDir property.
• start<environment>Sever : Starts the TeamCity Server for the environment, requires the environment homeDir and dataDir properties to be defined.
• stop<environment>Server : Stops the TeamCity Server for the environment, requires the environment homeDir property to be defined.
• start<environment>Agent : Starts the default TeamCity Build Agent for the environment, requires the environment homeDir property to be defined.
• stop<environment>Agent : Stops the default TeamCity Build Agent for the environment, requires the environment homeDir property to be defined.
• install<environment> : Downloads and installs TeamCity for the environment, this tasks uses the downloadBaseUrl and the environment homeDir properties.

==== Examples

[source,groovy] [subs="attributes"]

teamcity {
    // Use TeamCity {example-api-version} API
    version = '{example-api-version}'

    server {
        // Locate the plugin descriptor in the root directory of the project
        descriptor = file('teamcity-plugin.xml')
    }

    environments {
        // use a local web server for downloading TeamCity distributions
        baseDownloadUrl = "http://repository/"

        // store the downloaded TeamCity distributions in /tmp
        downloadsDir = '/tmp'

        // base properties for TeamCity servers and data directories
        baseHomeDir = 'teamcity/servers'
        baseDataDir = 'teamcity/data'

        teamcity91 {
            version = '9.1.7'
            javaHome = file('/opt/jdk1.7.0_80')
            // Add to the default server options
            serverOptions '-Dproperty=value'
            serverOptions '-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5500'
        }

        teamcity20172 {
            version = '2017.2.4'
            downloadUrl = 'http://repository/teamcity/TeamCity-2017.2.4.tar.gz'
            homeDir = file("$rootDir/teamcity/servers/TeamCity-2017.2.4")
            dataDir = file("$rootDir/teamcity/data/2017.2")
            javaHome = file('/opt/jdk1.8.0_202')
            // Replace the default server options
            serverOptions = '-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5500'
        }

        'teamcity2018.2' {
            version = '2018.2.2'
            javaHome = file('/opt/jdk1.8.0_202')
        }
    }
}

The following example shows environments being configured using the Kotlin DSL.

[source,groovy] [subs="attributes"] .build.gradle.kts

extra["downloadsDir"] = project.findProperty("downloads.dir") ?: "${rootDir}/downloads"
extra["java7Home"] = project.findProperty("java7.home") ?: "/opt/jdk1.7.0_80"
extra["java8Home"] = project.findProperty("java8.home") ?: "/opt/jdk1.8.0_202"


teamcity {
    version = "{example-api-version}"

    server {
        descriptor = file("teamcity-plugin.xml")
    }

    environments {
        baseDownloadUrl = "http://repository/"
        downloadsDir = extra["downloadsDir"] as String
        baseHomeDir = "teamcity/servers"
        baseDataDir = "${rootDir}/data"

        operator fun String.invoke(block: TeamCityEnvironment.() -> Unit) {
            environments.create(this, closureOf<TeamCityEnvironment>(block))
        }

        "teamcity9" {
            version = "9.1.7"
            javaHome = file(extra["java7Home"])

            // Add to the default server options
            serverOptions("-Dproperty=value")
            serverOptions("-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5500")
        }

        create("teamcity2017.2") {
            version = "2017.2.4"
            javaHome = file(extra["java8Home"] as String)

            // Replace the default server options
            setServerOptions("-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5500")
        }

        register("teamcity2018.2") {
            version = "2018.2.2"
        }
    }
}

fun Project.teamcity(configuration: TeamCityPluginExtension.() -> Unit) {
    configure(configuration)
}

== Samples

The link:samples[samples] directory contains a number of projects using the plugin.

The following projects use the plugin.

• https://github.com/JetBrains/teamcity-aws-codedeploy-plugin[AWS CodeDeploy]
• https://github.com/JetBrains/teamcity-aws-codepipeline-plugin[AWS CodePipeline]
• https://github.com/JetBrains/teamcity-rust-plugin[Rust and Cargo Support]
• https://github.com/JetBrains/teamcity-process-output-parsers[Framework for process output parsers]
• https://github.com/JetBrains/teamcity-azure-plugin[Azure Support]
• https://github.com/JetBrains/teamcity-dotnet-plugin[.NET Core Support]
• https://github.com/JetBrains/teamcity-nuget-support[NuGet Support]
• https://github.com/JetBrains/teamcity-github-auth[TeamCity GitHub Auth]
• https://github.com/JetBrains/teamcity-commit-hooks[TeamCity Commit Hooks]
• https://github.com/pwielgolaski/teamcity-oauth[TeamCity oAuth authentication]
• https://github.com/codeamatic/teamcity-docker-runner[Docker Deploy]
• https://github.com/grundic/teamcity-web-parameters[Teamcity web parameters]
• https://github.com/grundic/teamcity-browser-notify[Teamcity browser notify]
• https://github.com/graf/digitalocean-teamcity-plugin[DigitalOcean Support]
• https://github.com/dmitry-zhuravlev/kobalt-runner-teamcity-plugin[Kobalt Runner]
• https://github.com/cprieto/tsqlt-teamcity[TeamCity test runner for the tSQLt testing framework]
• https://github.com/etiennestuder/teamcity-build-scan-plugin[Gradle Build Scan Integration]
• https://github.com/Vampire/teamcity-ssh-tunnel[TeamCity SSH Tunnel]