Gradle TeamCity plugin

The plugin provides support to develop TeamCity plugins, creating agent and server side archives, downloading and installing a TeamCity server and tasks to deploy, start and stop the server and agent.

Using the plugin

Apply the plugin to the build

The plugin is published on the Gradle Plugin Portal. The following code adds the plugin to your build script.

    buildscript {
      repositories {
        maven {
          url "https://plugins.gradle.org/m2/"
        }
      }
      dependencies {
        classpath "com.github.rodm:gradle-teamcity-plugin:1.0"
      }
    }

Plugins

The jar contains three 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.

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 depenencies 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 plugin when publishing the agent plugin archive.

Extension Properties

The following properties are defined in the teamcity configuration block. The version property controls the version of the TeamCity server-api added to the compile configuration and the version downloaded and installed. 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 '9.0'.
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 and tests-supprt dependencies to the compile and testCompile configurations. If the Java Plugin is not applied the plugin provides only the tasks to package the server side plugin archive if a plugin descriptor is defined.

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

TeamCity Server 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. The type property affects the type of descriptor generated.
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 root project and the project version.

The plugin descriptor properties are shown in the examples below and described in the TeamCity documentation for Server-Side Plugin Descriptor

TeamCity Server Plugin Tasks

serverPlugin : Builds and packages a TeamCity plugin.
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')

Examples

Plugin descriptor defined in the build script.

    teamcity {
        // Use TeamCity 8.1 API
        version = '8.1'

        // 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'
                useSeparateClassloader = true

                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.

    teamcity {
        // Use TeamCity 8.1 API
        version = '8.1'

        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']
        }
    }

TeamCity Environments Configuration

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

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

downloadsDir : The directory the TeamCity installers are downlowded 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 '9.0'.
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 plguin development settings are described on the 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.

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.
undeployFrom<environment> : Undeploys 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.

Environments allow a plugin to be tested against multiple versions for TeamCity.

    teamcity {
        // Use TeamCity 8.1 API
        version = '8.1'

        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'

            teamcity81 {
                version = '8.1.5'
                javaHome = file('/opt/jdk1.7.0_80')
            }

            teamcity90 {
                version = '9.0.5'
                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'
            }

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

TeamCity Agent Plugin

The plugin when applied with the Java Plugin, adds the JetBrains Maven repository and adds the TeamCity agent-api and tests-supprt dependencies to the compile and testCompile 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.

TeamCity Agent Plugin 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. The type property affects the type of descriptor generated.
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 root project with '-agent' appended and the project version.

The plugin descriptor properties are shown in the examples below and described in the TeamCity documentation for Agent-Side Plugin Descriptor

TeamCity Agent Plugin 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.
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')

Examples

Agent side plugin descriptor

    teamcity {
        version = teamcityVersion

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

Agent tool descriptor

    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')
                }
            }
        }
    }

Samples

The samples directory contains a number of projects using the plugin.

The following projects use the plugin.

mkobit / gradle-teamcity-plugin Goto Github PK