Unable to render embedded object: File (TeamCity48.png) not found.

TeamCity 2018.x Documentation

Documentation for Previous Versions

Icon

You are viewing the documentation of TeamCity 2018.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

 

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Note

After enabling Kotlin for project settings, editing of the project in the web UI may not be available right after the switch. TeamCity needs to detect its own commit in the repository, and only after that editing will be enabled. Usually it takes a minute or two.

Anchor
portableDSL
portableDSL

Project Settings Structure

After the commit to the repository, you will get the the .teamcity settings directory with the following files:

...

Note

To get familiar with Kotlin API, see the online documentation on your local server, accessible via the link on the Versioned Settings project tab in the UI or by running the mvn -U dependency:sources command in the IDE. Refer to the documentation on the public TeamCity server as an an example.

You can also use the Download settings in Kotlin format option from the project Actions menu. For instance, you can find a project that defines some settings that you want to use in your Kotlin DSL project and use this "download" action to see what the DSL generated by TeamCity looks like.

Anchor
EditingKotlinsettingsinUI
EditingKotlinsettingsinUI

Patches

TeamCity allows editing of a project via the web interface, even though the project settings are stored in Kotlin DSL. For every change made in the project via the web interface, TeamCity will generate a patch in the Kotlin format, which will be checked in under the project patches directory with subdirectories for different TeamCity entities. For example, if you change a build configuration, TeamCity will submit the .teamcity/patches/buildTypes/<id>.kt script to the repository with necessary changes.

...

  • id is the absolute id of the project, the same id we'll see in browser address bar if we navigate to this project
  • parentId is the absolute id of a parent project where this project is attached
  • uuid is some unique sequence of characters.
    The uuid is something which associates a project, build configuration or VCS root with its data. If the uuid is changed, then the data is lost. The only way to restore the data is to revert the uuid to the original value. On the other hand, the id of an entity can be changed freely, if the uuid remains the same. This is the main difference of the non-portable DSL format from portable. The portable format does not require specifying the uuid, but if it happened so that a build configuration lost its history, one has to reattach it again via the web interface.

Patches

In case of non-portable DSL, patches are stored under the project patches directory of .teamcity:

...

To use an external library in your Kotlin DSL code, add a dependency on this library to the .teamcity/pom.xml file in the settings repository and commit this change so that TeamCity detects it. Then, before starting the generation process, the TeamCity server will fetch the necessary dependencies from the Maven repository, compile code with them, and then start the settings generator.

FAQ and Common Problems

How to

...

Add .teamcity as a

...

New Module to a

...

Project?

Question: How to add the .teamcity settings directory as a new module to an existing project in IntelliJ IDEA?

...

  • Fix the URL in the Kotlin DSL in the version control and push the fix.
  • Disable versioned settings to enable the UI.
  • Fix the URL in the VCS root in the UI.
  • Enable versioned settings with same VCS root and the Kotlin format again, TeamCity will detect that the repository contains the .teamcity directory and ask you if you want to import settings.
  • Choose to import settings.

How to

...

Read Files in Kotlin DSL

Problem: I want to generate a TeamCity build configuration based on the data in some file residing in the VCS inside the .teamcity directory

...