Automated CI/CD of Multiple Projects Using TeamCity’s Kotlin DSL

In a previous article, I described a way to organize low-latency products as multiple code bases which are bound together with a Maven Bill of Materials (BOM). Understandably, this requires setting up continuous integration and deployment for a large number of similar projects. Maintaining such a setup manually in the face of change while ensuring its consistency will take a lot of effort.  In this article, I will describe how the team at Chronicle Software has tackled these issues in different projects by writing code that does this for us, in the form of Kotlin DSL for TeamCity.

This guide will show how to configure the same set of CI/CD builds for multiple Maven project repositories of similar layouts programmatically, following the DRY (don’t repeat yourself) principle. Following it will require a base knowledge of git, Maven, and TeamCity but would not require knowledge of the Kotlin language, since all of the displayed code is self-explanatory.

Once you configure versioned settings for a TeamCity project, it will push a skeleton Maven configuration project to a repository of choice, which we will be working with.

Configuration as Code

First, we introduce our own product management code into configuration scripts by adding the dependency to .teamcity/pom.xml. If you need any specific dependency settings file used during dependency resolving, such as specifying credentials for internal Maven repositories, upload them to the TeamCity <Root project>’s Maven Settings tab under the name mavenSettingsDsl.xml.

<dependency>
  <groupId>software.chronicle</groupId>
  <artifactId>release-automation</artifactId>
  <version>1.0.21</version>
</dependency>

Then we start working on .teamcity/setting.kts Kotlin script file, adding all of our products as TeamCity projects in a data-driven fashion based on our existing Products enum:

version = "2021.2"

project {
   description = "Chronicle Software’s Low Latency Microservice Products"
   template(GitHubTriggerNotify)

   subProjects(*subProjectsFromReleaseAutomation())
}

fun subProjectsFromReleaseAutomation(): Array<Project> {
   val projects = ArrayList<Project>()

   for (product in Product.values()) {
       projects.add(Project {
           id = RelativeId(product.name)

           name = product.name
           description = product.gitUrl().replace("[email protected]:",
                             "https://github.com/").replace(".git", "")

Continuing the same script, every product will have its GitHub repository set up:

           vcsRoot(GitVcsRoot {
               id = RelativeId(product.toString() + "_GitHub")

               name = product.name + " GitHub Repository"

               url = product.gitUrl()
               branch = "refs/heads/main"
               branchSpec = "+:refs/heads/(*)"

               authMethod = uploadedKey {
                   uploadedKey = "teamcity-kotlin-dsl"
               }
           })

After that, a snapshot deploying build is configured for every product, to be triggered when a commit is pushed to main branch and deploy the SNAPSHOT artifacts to our Maven repository:

           buildType {
               id = RelativeId(product.name + "_DeploySnapshot")
               name = "Deploy Snapshot"

               description = product.name + " SNAPSHOT artifacts deployment"

               vcs {
                   root(RelativeId(product.toString() + "_GitHub"))
               }
              
               triggers {
                   vcs {
                       id = "TriggerOnMain"
                       branchFilter = "+:<default>"
                   }
               }

               steps {
                   maven {
                       id = "CleanDeploy"
                       name = "clean deploy"
                       goals = "clean deploy"
                       userSettingsSelection = "kotlinDslBuildSettings.xml"
                       jvmArgs = "-ea"
                       jdkHome = "%env.JDK_1_8_x64%"
                   }
               }
           }

Secondly, a GitHub pull request testing build is added based on a template defined elsewhere, then returning the resulting TeamCity projects list, with a repository and two builds each:

           buildType {
               templates(RelativeId("GitHubTriggerNotify"))
               id = RelativeId(product.name + "_PullRequest")
               name = product.name + " Pull Request"

               description = product.name + " regular build for testing a Pull Request"

               vcs {
                   root(RelativeId(product.toString() + "_GitHub"))
               }
           }
       })
   }

   return projects.toTypedArray()
}

In a separate file, .teamcity/GitHubTriggerNotify.kt, a template is defined which will run tests and report results to GitHub pull request branches:

object GitHubTriggerNotify : Template({
   RelativeId("GitHubTriggerNotify")
   name = "Template for pull request builds"
   description = "Triggered by branch changes, posts results to GitHub"

   triggers {
       vcs {
           id = "TriggerAll"
           branchFilter = """
                   +:*
                   -:<default>
               """.trimIndent()
       }
   }

   failureConditions {
       executionTimeoutMin = 60
   }

   features {
       commitStatusPublisher {
           id = "NotifyGitHub"
           publisher = github {
               githubUrl = "https://api.github.com"
               authType = personalToken {
                   token = DslContext.getParameter("GitHub-PR-notification-API-token")
               }
           }
           param("github_oauth_user", "our-team-city")
       }
   }
})

SSH keys and API tokens should be specified separately, which is not shown in this guide.

Conclusion

The demonstrated approach allows us to not only keep our TeamCity configuration in a versioned and audited state, but it also dramatically reduces the line count of configuration scripts as we are iterating our products and defining multiple build configurations per product without repeating the specifics, while also making sure that all builds adhere to exactly the same build conditions and stages. It makes sense to disable any manual configuration for the project and only rely on explicit, thought-out configuration code changes.

Resources

TeamCity On-Premises Kotlin DSL documentation