Configuration as Code, Part 5: Using DSL extensions as a library

  1. Getting started with Kotlin DSL
  2. Working with configuration scripts
  3. Creating build configurations dynamically
  4. Extending Kotlin DSL
  5. Using libraries
  6. Testing configuration scripts

In the previous post, we have seen how to extend TeamCity’s Kotlin DSL by adding new abstractions. If the new abstraction is generic enough, it would make sense to reuse it in different projects. In this post, we are going to look at how to extract the common code into a library. We will then use this library as a dependency in a TeamCity project.

Maven project and dependencies

In the first post of this series, we started out by creating an empty project in TeamCity. We then instructed the server to generate the configuration settings in Kotlin format.

The generated pom.xml file pointed at two repositories and a few dependencies. This pom.xml is a little excessive for our next goal, but we can use it as a base, and remove the parts that we don’t need for the DSL library.

The two repositories in the pom.xml file are jetbrains-all, the public JetBrains repository, and teamcity-server that points to the TeamCity server where we generated the settings. The reason why the TeamCity server is used as a repository for the Maven project is that there may be some plugins installed that extend the TeamCity Kotlin DSL. And we may want to use those extensions for configuring the builds.

However, for a library, it makes sense to rely on a minimal set of dependencies to ensure portability. Hence, we keep only those dependencies that are downloaded from the public JetBrains Maven repository and remove all the others. The resulting pom.xml lists only 3 libraries: configs-dsl-kotlin-{version}.jar, kotlin-stdlib-jdk8-{version}.jar, and kotlin-script-runtime-{version}.jar.

The code

It’s time to write some code! In fact, it’s already written. In the previous post, we have introduced the new abstraction, the sequence, to automatically configure the snapshot dependencies for the build configurations. We only need to put this code into a *.kt file in our new Maven project.

teamcity-pipelines-dsl-lib

We have published the example project on GitHub. Pipelines.kt lists all the extensions to the TeamCity DSL. That’s it! We now can build the library, publish it, and use it as a dependency in any TeamCity project with Kotlin DSL.

Using the library

The new library project is on GitHub, but we haven’t published it to any Maven repository yet. To add it as a dependency to any other Maven project we can use the awesome jitpack.io. The demo project demonstrates how the DSL library is applied.

Here’s how we can use the library:

1. Add the JitPack repository to the pom.xml file:

2. Add the dependency to the dependent DSL project’s pom.xml:

The version is equal to a tag in the GitHub repository:

teamcity-pipelines-dsl-tags

Once the IDE has downloaded the dependencies, we are able to use the DSL extensions provided by the library. See settings.kts of the demo project for an example.

using-the-library

Summary

TeamCity allows adding 3rd-party libraries as Maven dependencies. In this post, we have demonstrated how to add a dependency on the library that adds extensions to the TeamCity Kotlin DSL.

About Anton Arhipov

Developer Advocate at JetBrains
This entry was posted in Features, How-To's, Tips&Tricks and tagged . Bookmark the permalink.

6 Responses to Configuration as Code, Part 5: Using DSL extensions as a library

  1. jonnii says:

    We’ve done this using a submodule instead of a maven package, which (one could argue) is definitely a worse solution, but has the benefit of having a great development time experience.

  2. Alexander Samuilov says:

    Thank you for this guide, Anton.

    I would like to use a private Maven repository based on Azure Storage Account (https://egkatzioura.com/2018/04/09/host-your-maven-artifacts-using-azure-blob-storage/). Where I should store the Storage Account key so that TeamCity can authorize in the Maven repository?

  3. Kieron Wilkinson says:

    This is a really great series Anton, thank you.

    I was really looking forward to the testing post. Are you still planning to do that one? I notice is not mentioned in the later articles.

    • Anton Arhipov says:

      Hello! Yes, the testing post is in plans as well as a few more.
      I forgot to add it in the list for the last post, thanks for noticing!

Leave a Reply

Your email address will not be published. Required fields are marked *