Kotlin DSL

XML 形式で設定をバージョン管理に保存することに加えて、TeamCity では (Kotlin 言語に基づく) DSL で設定を保存できます。

バージョン管理に保存された DSL を使用すると、設定をプログラムで定義できます。 Kotlin は静的型付けのため、IDE で自動補完機能を自動的に利用でき、使用可能な API オプションをはるかに簡単に見つけられます。

TeamCity で Kotlin DSL を使用する方法については、ブログ投稿シリーズと推奨リファクタリングの記事をご覧ください。

TeamCity Kotlin DSL ビデオチュートリアルをさらに見る:

Kotlin DSL の仕組み

Kotlin 形式のバージョン設定が有効になっている場合、TeamCity は現在の設定を指定された設定リポジトリにコミットします。

設定リポジトリで新しいコミットが検出されると、TeamCity はこのコミットで見つかった DSL スクリプトを実行し、その結果を TeamCity サーバーの設定に適用するか、プロジェクトのバージョン対応設定タブでエラーを報告します。

注: DSL スクリプトは、本質的には TeamCity 構成ファイルを記述する別の方法です。 DSL スクリプトは、ビルドの実行方法を直接制御しません。たとえば、ビルドの現在の状態に応じて条件を設定し、何かを変更することは不可能です。スクリプト実行の結果は構成ファイルであり、TeamCity サーバーによって読み込まれ、その後、新しくトリガーされたビルドの動作が変更されます。

DSL は Kotlin プログラミング言語のコードであるため、この言語でサポートされるすべてのパラダイムが利用可能です。たとえば、TeamCity テンプレートを使用する代わりに、プロジェクトの共通設定をカプセル化する関数またはクラスを作成できます。プログラミングスキルをお持ちの場合は、ビルド構成設定をより自然に再利用できます。

DSL は、同様のビルド構成を大量に作成する必要がある場合にも適しています。この場合、これらは非常に単純なコードで生成できますが、DSL がなければ、これらすべての構成を作成するユーザーインターフェースでかなりの時間を費やす必要があります。

Pipelines における Kotlin DSL

Pipelines は、使い慣れた TeamCity エクスペリエンスを再構築し、複雑な CI/CD ワークフローを最も直感的に設計できる方法を提供することを目指しています。ネイティブな構成コード形式は YAML です。

バージョン 2026.1 以降、親プロジェクトでバージョン管理された設定が有効になっている場合、パイプライン設定は自動的に Kotlin DSL に変換されます。詳細については、パイプライン Kotlin DSL を参照してください。

Kotlin DSL を始める

この Kotlin チュートリアル(英語)は、ほとんどの Kotlin 機能をすばやく学習できます。サーバーの Kotlin DSL API ドキュメントは、 <TeamCity サーバー:ポート>/アプリ/dsl-ドキュメント/インデックス.html で入手できます。最新の TeamCity バージョン向け Kotlin DSL API ドキュメントも参照できます。

TeamCity で Kotlin DSL の使用を開始するには、サーバー上に空のサンドボックスプロジェクトを作成し、次の手順に従います。

プロジェクトのためのバージョン対応設定を有効にします。
必要な VCS ルートを選択します。正しい資格情報が指定されていることを確認してください。匿名認証を使用している場合、TeamCity は変更をコミットできません。
形式として Kotlin を選択します。
適用をクリックすると、TeamCity は生成された Kotlin ファイルをリポジトリにコミットします。

リポジトリにコミットすると、 .teamcity 設定ディレクトリに次のファイルが含まれます。

settings.kts — すべてのプロジェクト構成が含まれるメインファイル。
pom.xml — TeamCity と外部 IDE (Kotlin プロジェクトを開くために使用するもの) が、DSL コードのコンパイルと実行に必要な依存関係を解決できるようにします。

IntelliJ IDEA で Kotlin プロジェクトを編集する

IntelliJ IDEA で TeamCity Kotlin DSL プロジェクトを作成、編集、デバッグできます (Ultimate 版と Community 版の両方がサポートされています)。

新規プロジェクトの作成

.teamcity 設定ディレクトリを新しいモジュールとして IntelliJ IDEA の既存のプロジェクトに追加するには、以下の手順に従います。

ファイル | プロジェクト構造に移動するか、 Ctrl + Shift + Alt + S を押します。
プロジェクト設定セクションでモジュールを選択します。
プラス記号をクリックし、モジュールをインポートを選択して、プロジェクト設定を含むディレクトリを選択します。確認をクリックして、ウィザードに従います。
適用をクリックします。新しいモジュールがプロジェクト構造に追加されます。

既存のプロジェクトを開く

IntelliJ IDEA で Kotlin DSL プロジェクトを開くには、 .teamcity/pom.xml ファイルをプロジェクトとして開きます。必要な依存関係はすべて、すぐに自動的に解決されます。

すべての依存関係が解決されている場合、 settings.kts に赤色のエラーは表示されません。すでに IntelliJ IDEA プロジェクトがあり、それに Kotlin DSL モジュールを追加したい場合は、新規プロジェクトの作成セクションの手順に従ってください。

DSL ドキュメントのダウンロード

ローカル TeamCity サーバーの DSL ドキュメントは、常に <TeamCity_サーバー_URL/アプリ/dsl-ドキュメント/インデックス.html で利用できます。このドキュメントを IDE にインポートすることもできます。こうすることで、.kts ファイルを編集するときにオブジェクトの説明と例を表示できるようになります。

これらのソースをダウンロードするには、Maven パネルで対応するオプションをクリックします ...

... または、 mvn -U 依存関係:sources コマンドを実行します。

インポートされたドキュメントは、ポインタをキーワードの上に置くと表示されるヒントとして表示されます。スタンドアロンウィンドウで開くには、ドキュメントホットキー (デフォルトでは F1) を押すか、表示 | ツール Windows | ドキュメントをクリックするか、ヒントパネルの省略記号ボタンを使用します。

Kotlin DSL の編集

空のプロジェクトを作成すると、IDE の settings.kts に表示されます。

import jetbrains.buildServer.configs.kotlin.*
/* some comment text */
version = "2025.11"

project {
}

ここで、 project {} は、DSL で設定を定義する現在のプロジェクトを表します（DSL コードでは、 _Self と呼ばれることもあります）。これは、前の手順でバージョン設定を有効にしたプロジェクトと同じです。このプロジェクト ID と名前は、特別な DslContext オブジェクトを介してアクセスできますが、DSL コードを介して変更することはできません。

次の例は、コマンドラインスクリプトを使用してビルド構成を追加する方法を示しています。

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.script 

version = "2025.11"

project {
  buildType {
    id("HelloWorld")
    name = "Hello world"
    steps {
        script {
            scriptContent = "echo 'Hello world!'"
        }
    }
  }
}

   

ここで、 ID は TeamCity のビルド構成 IDフィールドの値として使用されます。上記の例では、 ID を指定する必要があります。省略すると、このスクリプトから設定を生成しようとすると検証エラーが発生します。

同じビルド構成を定義する別の方法もあります。

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.script 

version = "2025.11"

project {
  buildType(HelloWorld)
}

object HelloWorld: BuildType({
    name = "Hello world"
    steps {
        script {
            scriptContent = "echo 'Hello world!'"
        }
    }
})

   

この場合、TeamCity がクラス名 (この場合は HelloWorld) に基づいて ID を生成するため、 id() 関数呼び出しの使用は任意です。

settings.kts ファイルで必要な変更を行った後、それらをリポジトリに送信できます。TeamCity が検出して適用します。スクリプト実行中にエラーがない場合、プロジェクトに "Hello world" という名前のビルド構成が表示されます。

XML 構成ファイルをローカルで生成する

Kotlin プロジェクト用に提供されている pom.xml ファイルには、DSL スクリプトから TeamCity XML 構成ファイルをローカルで生成するために使用できる 生成 タスクがあります。このタスクは、IDE（Maven ツールウィンドウのプラグイン | teamcity-configs | teamcity-configs:生成ノードを参照）またはコマンドラインから開始できます。

mvn teamcity-configs:generate

タスクの実行結果は、 .teamcity/ターゲット/generated-configs ディレクトリに配置されます。

Kotlin DSL スクリプトのデバッグ

IntelliJ IDEA を使用している場合は、Maven タスクのデバッグを簡単に開始できます。

表示 | ツール Windows | Maven プロジェクトに移動します。 Maven プロジェクトツールウィンドウが表示されます。
タスクノードを見つける: プラグイン | teamcity-configs | teamcity-configs:生成、デバッグオプションはタスクのコンテキストメニューで利用できます。

Web UI からプロジェクト設定を編集する

プロジェクト設定が Kotlin DSL に保存されている場合でも、TeamCity では Web インターフェースからプロジェクト設定を編集できます。 DSL スクリプトが手動で変更されていない場合、つまり TeamCity によって生成され、リポジトリ内で同じ状態のままである場合、Web UI からの変更はこれらの生成済みファイルに直接適用されます。

ただし、生成されたファイルが変更されている場合、TeamCity は .kt または .kts ファイルのどの部分を変更すべきか分からなくなるため、パッチを生成する必要があります。

ポータブル DSL の場合、パッチは .teamcity/patches ディレクトリの下に配置されます。例:

patches/projects/<relative project id>.kts
patches/buildTypes/<relative build configuration id>.kts  
patches/templates/<relative vcs root id>.kts  
patches/vcsRoots/<relative build configuration id>.kts  

  

パッチの例

次のパッチは、ビルドファイルをきれいにする (Swabra) ビルド機能を ID SampleProject_ビルド のビルド構成に追加します。

changeBuildType(RelativeId("SampleProject_Build")) { // this part finds the build configuration where the change has to be done  
    features {
        add {
            // this is the part which should be copied to a file which generates settings for SampleProject_Build build configuration
            swabra {
                filesCleanup = Swabra.FilesCleanup.DISABLED
            }
        }
    }
}

   

変更をパッチファイルから対応する .kt または .kts ファイルに移動し、パッチファイルを削除することを意味します。パッチの生成により、プロジェクト設定の編集にユーザーインターフェースを引き続き使用できると同時に、Kotlin DSL スクリプトの利点を利用できます。

ID 変更後にビルド履歴を復元する

ポータブル DSL に基づくプロジェクト内のビルド構成を識別するため、TeamCity は DSL でこのビルド構成に割り当てられた IDを使用します。 DSL コードで行った変更が TeamCity の対応するビルド構成に一貫して適用されるよう、この ID を一定に保つことをお勧めします。

ただし、DSL でビルド構成 ID を変更すると、TeamCity には、以前の ID の構成が削除され、新しい ID の新しい構成が単一のコミットで作成されたように見える点に注意してください。この場合、TeamCity はビルド履歴を新しい ID のビルド構成に自動的に関連付けます。これは、複数のビルド構成の ID が同じコミット内で変更された場合にも当てはまります: TeamCity は、削除された構成に最も近い構成にビルド履歴を割り当てるロジックを使用します。このアクションのエントリはサーバーログに表示されます。

ビルド構成 ID の変更に二つのコミット (以前の ID の構成を削除するコミットと、新しい ID のビルド構成を追加するコミット) を使用すると、新しいビルド構成にはビルド履歴が含まれなくなります。 TeamCity はクリーンアップされるまで 5 日間ビルド履歴を保持し、この期間中は履歴を手動で復元できます。

ビルド構成 ID を変更した後にビルド履歴を手動で復元するには、ID が変更されたビルド構成のビルド構成設定に移動し、アクションメニューを開いて、ビルド履歴を添付をクリックします。「ビルド履歴を添付」タブにリダイレクトされます。切り離されたビルド履歴を選択し、添付をクリックします。

UI で DSL を表示する

UI でビルド構成の設定を表示しているときに、サイドバーのコードとして表示をクリックできます: 現在の構成の DSL 表現が表示され、表示中の設定 (たとえば、ビルドステップ、トリガー、依存関係) がハイライトされます。戻るには、 UI で編集をクリックします。

これは、ビルド機能またはトリガーを DSL スクリプトに追加する必要があり、DSL コードがどのように見えるかわからない場合に特に便利です。

カスタム Kotlin ライブラリを追加

TeamCity では、デフォルトの Kotlin 構文を拡張するカスタム .jar ライブラリをアップロードできます。例: 標準の BuildType(英語) クラスから継承されたカスタム マイビルドタイプ クラスを宣言するカスタムライブラリがあるとします。

package src.main.kotlin.builds

public open class MyBuildType : jetbrains.buildServer.configs.kotlin.BuildType {
    // ...
}

TeamCity で管理 | DSL ライブラリに移動し、 DSL ライブラリをアップロードをクリックします。これにより、 .jar ライブラリをアップロードし、オプションの グループ ID、 アーティファクト ID、 バージョン Maven 座標でタグ付けできるダイアログが呼び出されます。

カスタムライブラリの使用を開始するには、 Maven 依存関係(英語)も追加する必要があります。ステートメントをコピーするには、スニペットをクリックします ...

... それを必要なプロジェクトの pom.xml ファイルに貼り付けます。

<dependencies>
    ...
    <dependency>
        <groupId>org.jetbrains.teamcity</groupId>
        <artifactId>dsl-library</artifactId>
        <version>1.0-SNAPSHOT</version>
    </dependency>
</dependencies>

  

その後、このライブラリのオブジェクトを .kts 設定で使用できるようになります。

import src.main.kotlin.builds.MyBuildType

version = "2024.12"

val myConf = MyBuildType("Custom Build Type")

project {
    buildType(myConf)
}

// ...

ポータブル DSL スクリプトの利点の 1 つは、同じサーバーまたは複数のサーバー上の複数のプロジェクトでスクリプトを使用できることです（名前はポータブルです）。

新しいプロジェクトを作成するときは、プロジェクト設定を Kotlin DSL フォーマットで保存するリポジトリを TeamCity に指定します。 TeamCity には、選択できる三つのオプションが表示されます：

同期を有効にせずにこれらの設定を適用します。その後、新しいプロジェクトをカスタマイズできますが、これらの編集はリモートリポジトリにコミットされません。
これらの設定を適用し、同期を有効化します。 TeamCity UI で行った変更はリモート DSL スクリプトを更新し、その逆に、VCS 側でスクリプトを編集すると TeamCity プロジェクトが更新されます。
設定を無視して、最初から新しいプロジェクトを作成します。

バージョン 2024.07 以降、Kotlin スクリプトはリモートリポジトリ内の任意のカスタムの場所に保存できます。ただし、新しいプロジェクトを作成する場合、TeamCity が現在既存の DSL スクリプトを検出できるのは、それらがデフォルトの .teamcity フォルダーに保存されている場合のみです。回避策として、空のプロジェクトを作成して、次の操作を実行してください。

プロジェクト設定のバージョン対応設定タブに移動します。
同期が有効化されていますを確認してください。
VCS 内の設定パスフィールドに設定ディレクトリへのパスを指定します。
リモートに保存された DSL スクリプトをインポートするには、 VCS からプロジェクト設定を読み込む… をクリックします。

プロジェクトにリモートで保存された設定が適用されたら、同期が不要になった場合は無効にすることができます。

DSL でコンテキストパラメーターを使用する

TeamCity UI で構成されたコンテキストパラメーターを使用して、DSL 生成動作をカスタマイズできます。コンテキストパラメーターは、UI のプロジェクトバージョン設定の一部として指定されます。

コンテキストパラメーターを使用すると、単一の Kotlin DSL コードを維持し、同じ TeamCity サーバー上の異なるプロジェクトで使用できます。これらの各プロジェクトは独自のコンテキストパラメーターの値を持つことができ、同じ DSL コードはこれらのパラメーターの値に基づいて異なる設定を生成できます。

チュートリアルを視聴し、プロジェクトでコンテキストパラメーターを使用する方法については、ブログ(英語)にアクセスしてください。

TeamCity プロジェクトでコンテキストパラメーターを使用するには、(1) UI のプロジェクトバージョン設定で定義し、(2) プロジェクト DSL で参照する必要があります。

UI でコンテキストパラメーターを管理
プロジェクトコンテキストパラメーターはバージョン対応設定 | コンテキストパラメータータブで管理できます。

パラメーターを追加、編集、または削除して保存をクリックすると、TeamCity は DSL 構成を再読み込みし、変更された値をプロジェクト設定に適用します。
DSL でコンテキストパラメーターを参照
DSL コードでコンテキストパラメーターを参照するには、 getParameter() メソッドを DslContext オブジェクトで使用します。このパラメーターのデフォルト値を任意の 2 番目の引数として指定できます: getParameter("<パラメーター名>", "<デフォルト値>")。
次の例は、DSL でコンテキストパラメーターを使用する方法を示しています。
object Build : BuildType({ /* a context parameter that defines a build configuration name; its default value is `Test Build` */ name = "${DslContext.getParameter("BuildName", "Test Build")}" script { scriptContent = "echo Build Successful" } /* disable the last build step depending on the value of the `environment` parameter */ script { scriptContent = "echo Deploy" enabled = DslContext.getParameter(name = "Environment") != "Staging" } })

各コンテキストパラメーターには、DSL で設定されたデフォルト値、または UI で設定されたプロジェクト固有の値のいずれかが必要です。 DSL からプロジェクトを作成するか、プロジェクトのバージョン設定を更新すると、TeamCity は値が不足しているすべてのコンテキストパラメーターを検出し、設定するよう求めます。

Maven で DSL コンテキストパラメーターを定義する

コンテキストパラメーターの特定の値を定義するには、 pom.xml ファイルに <コンテキストパラメーター> ブロックを追加します。

コンテキストパラメーターを使用した Maven プラグインの例:

<plugin>
    <groupId>org.jetbrains.teamcity</groupId>
    <artifactId>teamcity-configs-maven-plugin</artifactId>
    <version>${teamcity.dsl.version}</version>
    <configuration>
        <format>kotlin</format>
        <dstDir>target/generated-configs</dstDir>
 
        <contextParameters>
            <BuildName>Test</BuildName>
            <Message>Test</Message>
        </contextParameters>
 
    </configuration>
</plugin>


   

これは、DSL スクリプトが DSL コンテキストパラメーターのさまざまな値に対して設定を正しく生成することをローカルで確認する場合に便利です。

グローバルサーバー設定の保存と管理

Kotlin DSL または XML 設定を VCS に保存すると、プロジェクトやビルド構成にコードとしての構成アプローチを利用できるようになります。プロジェクトの階層を指定したり、個々の構成を管理したり、ステップの設定やパラメーターを動的に変更したりすることができます。

ただし、この方法では、サーバー全体の設定 (ユーザーおよびユーザーグループの設定、クリーンアップルール、通知、認証モジュール、ライセンスなど) を管理することはできません。サーバー管理を自動化するには、必要な設定を HCL 言語形式で定義し、 HashiCorp Terraform(英語) を使用して管理します。 Terraform が TeamCity サーバーインスタンスと通信できるようにするには、専用の TeamCity Terraform Provider を Terraform 構成に追加します。

さらに詳しく知る:

高度なトピック

ビルドチェーン DSL 拡張

TeamCity Kotlin DSL は、パイプラインスタイルでビルドチェーンを構成する別の方法を提供します。

DSL コードでは、連鎖するビルドを 1 つずつ列挙する 順次 メソッドによって、プロジェクト内でビルドチェーンが宣言されます。チェーン内で互いに並列に実行されるビルドをグループ化するには、 並列 メソッドを使用します。 並列 ブロックの後に続く最初のビルドは、先行するすべての並列ビルドに依存します。

次の例は、アプリケーションをコンパイルおよびデプロイするための一般的なパイプラインを示しています。

project {
  buildType(Compile)
  buildType(Test1)
  buildType(Test2)
  buildType(Package)
  buildType(Deploy)
  buildType(Extra) 
  ... 

    sequential  {
      buildType(Compile)
      parallel (options = { onDependencyFailure = FailureAction.CANCEL }) { // non-default snapshot dependency options
        dependsOn(Extra) // extra dependency to be defined in all builds in the parallel block
        buildType(Test1)
        buildType(Test2)
      }
      buildType(Package)
      buildType(Deploy)
    }
}

   

パイプラインスタイルでビルドチェーンを定義する場合は、参照されるビルド構成自体に明示的なスナップショットの依存関係が定義されていないことを確認してください。

上記の例では、ビルドチェーンはすでに宣言されているビルドを参照しています。または、簡略化された構文を使用して、チェーン宣言の後にリストされたすべてのビルドを登録できます。

project {

 // build chain definition:
  val buildChain = sequential {
   ...
  }

  // register all build configurations, referenced in the chain, in the current project:
  buildChain.buildTypes().forEach { buildType(it) }
}

   

明示的なスナップショットの依存関係は、 並列 ブロックと 順次 ブロックの両方内の dependsOn() ステートメントを介して定義でき、オプションのラムダ引数を使用して依存関係オプションを設定できます。暗黙的なスナップショット依存関係のオプションのデフォルト以外の値は、任意のブロックの オプション ラムダ引数を介して設定できます。

設定の検証

DSL API バージョン v2017_2+ を使用する設定は、TeamCity サーバーでの DSL 実行中に検証されます。 生成 タスクを使用して XML 構成ファイルを生成し、ローカルで検証を実行することもできます。

検証では、必須プロパティが指定されているかをチェックします。たとえば、次のようなビルドステップです。

buildType {
    ...
    steps {
        exec {
        }
    }
    ...
}

   

必須のパスプロパティが指定されていないという検証エラーが発生します。これは、UI で新しいビルドステップを作成するときに TeamCity が実行するチェックと似ています。

セットアップに関連する方法で検証を拡張することもできます。これを行うには、 validate() メソッドをオーバーライドする必要があります。例: 次のクラスは、Git の VCS ルートにカスタム検証を追加します。

open class MyGit() : GitVcsRoot() {
    constructor(init: MyGit.() -> Unit): this() {
        init()
    }

    override fun validate(consumer: ErrorConsumer) {
        super.validate(consumer) //perform basic validation

        url?.let {
            if (it.startsWith("git://") || it.startsWith("http://")) {
                consumer.consumePropertyError("url", "Insecure protocol, please use https or ssh instead")
            }
        }

        authMethod?.let {
            if (it is AuthMethod.CustomPrivateKey || it is AuthMethod.DefaultPrivateKey) {
                consumer.consumePropertyError("authMethod", "Prohibited authentication method, please use 'uploadedKey' instead")
            }
        }
    }
}

   

外部ライブラリを使用する機能

Kotlin DSL コードで外部ライブラリを使用でき、異なる Kotlin DSL ベースのプロジェクト間でコードを共有できます。

Kotlin DSL コードで外部ライブラリを使用するには、設定リポジトリ内の .teamcity/pom.xml ファイルにこのライブラリへの依存関係を追加し、TeamCity が検出できるようにこの変更をコミットします。その後、生成プロセスを開始する前に、TeamCity サーバーは Maven リポジトリから必要な依存関係を取得し、それらを使用してコードをコンパイルしてから、設定ジェネレーターを起動します。

プライベートリポジトリ内の外部ライブラリへのアクセスを確立できます。そのためには、 Maven 設定ファイル (英語) (mavenSettingsDsl.xml) で必要なすべての資格情報を指定し、ルートプロジェクトの Maven 設定ページにアップロードします。

DSL コンパイル

プロジェクトがリポジトリから DSL のバージョン管理された設定を読み込むと、TeamCity はそれらをすぐには適用せず、まずこのコードをコンパイルして失敗しないことを確認します。このコンパイルを実行する場所は、TeamCity サーバー上または空いているビルドエージェント上から選択できます。

コンパイル (実行) モードを変更するには、プロジェクト設定 | バージョン管理された設定ページで必要な動作を選択します。

ビルドエージェントで DSL をコンパイルする方法が一般的に推奨されますが、各モードにはそれぞれトレードオフがあります。

サーバー上

メリット

プロセス全体が単一のマシンで実行されるため、レイテンシが低くなります。
ビルドエージェントを占有しません。

デメリット

コードがメインサーバーで実行されるため、セキュリティは低くなります。コードはサーバーのサンドボックス化された領域でコンパイルされますが、完全に分離されているわけではありません。
サーバーリソースを占有します。
サーバーでは、同時に実行できる Kotlin DSL コンパイルの数が 10 に固定されています。
セキュリティ上の理由から、サーバー上でコンパイルされた Kotlin コードにはいくつかの制限があります。たとえば、親 .teamcity ディレクトリの外部にあるファイルの読み取り、ネットワーク呼び出し、サブプロセスの起動、ネイティブライブラリの読み込み、内部/JDK クラスのリフレクションの実行などはできません。

ビルドエージェント上

メリット

このタスクをサーバーから切り離し、一部のリソースを解放します。
コードはサーバー外の別のマシンで実行されるため、より安全です。
サーバーのサンドボックス制限の影響を受けません: ビルドエージェント群で許可される範囲で、同時コンパイルタスクをいくつでも実行でき、コンパイルされたコードは任意の操作を実行できます。

デメリット

本来はビルドを実行できるビルドエージェントを占有します。
クラウドエージェントで kDSL を実行すると、追加のホスティングコストが発生します。
オーバーヘッドが大きく、速度が低下する場合があります: コンパイルは空いているエージェントを待機し、クラウドエージェントの起動には追加の時間が必要です。

どちらのモードでも、Central のレート制限に違反しないように、 Maven Central ミラーを mavenSettingsDsl.xml ファイルで定義できます。

<?xml version="1.0" encoding="UTF-8"?>
<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd" xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <mirrors>
    <mirror>
      <mirrorOf>central</mirrorOf>
      <name>repo</name>
      <url>https://host/maven/proxy</url>
      <id>repo</id>
    </mirror>
  </mirrors>
</settings>

   

非ポータブル DSL

2018.1 より前の TeamCity バージョンでは、Kotlin DSL 設定に異なる形式が使用されていました。この古い非ポータブル形式のプロジェクトをインポートすると、TeamCity で作業できます。この場合、移植可能な DSL スクリプトを生成するオプションが使用可能になります。

TeamCity が非ポータブル DSL を生成すると、 .teamcity ディレクトリ内のプロジェクト構造は次のようになります。

pom.xml
<プロジェクト ID>/settings.kts
<プロジェクト ID>/Project.kt
<プロジェクト ID>/buildTypes/<ビルド構成 ID>.kt
<プロジェクト ID>/vcsRoots/<VCS ルート ID>.kt

<プロジェクト ID> は、バージョン対応設定が有効になっているプロジェクトの ID です。ビルド構成と VCS ルートを生成する Kotlin DSL ファイルは、対応するサブディレクトリに配置されています。

settings.kts

移植性のない形式では、各プロジェクトに次の settings.kts ファイルがあります。

package MyProject
import jetbrains.buildServer.configs.kotlin.*
/* ... */
version = "2025.11"

project(MyProjectId.Project)

これがプロジェクト設定生成のエントリポイントです。基本的には、プロジェクト設定を生成する Project インスタンスを表します。

Project.kt

Project.kt ファイルは次のようになります。

package MyPackage
import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.Project

object Project : Project({
   uuid = "05acd964-b90f-4493-aa09-c2229f8c76c0"
   id("MyProjectId")
   parentId("MyParent")
   name = "My project"
   ...
})


    

where:

ID はプロジェクトの絶対 ID で、このプロジェクトに移動したときにブラウザーのアドレスバーに表示されるものと同じ ID です
parentId は、このプロジェクトが接続されている親プロジェクトの絶対 ID です
uuid は一意の文字列です。
uuid は、プロジェクト、ビルド構成、または VCS ルートをそのデータに関連付ける一意の識別子です。 uuid が変更されると、データは失われます。データを復元する唯一の方法は、 uuid を元の値に戻すことです。一方、 uuid が同じままであれば、エンティティの ID は自由に変更できます。これが、非ポータブル DSL 形式とポータブル形式の主な違いです。ポータブル形式では uuid を指定する必要はありませんが、ビルド構成の履歴が失われた場合 (たとえば、ビルド構成の外部 ID を変更した場合) は、ビルド履歴を添付オプションをアクションメニューから使用して、履歴をビルド構成に再度関連付けることができます。詳細を参照してください。

移植不可能な DSL の場合、パッチは .teamcity のプロジェクトパッチディレクトリに保存されます。

<project id>/patches/projects/<uuid>.kts
<project id>/patches/buildTypes/<uuid>.kts
<project id>/patches/templates/<uuid>.kts
<project id>/patches/vcsRoots/<uuid>.kts

    

パッチの扱いはポータブル DSL と同じです。実際の設定をパッチからスクリプトに移動し、パッチを削除する必要があります。

DSL でのセキュア値の操作

一般に、TeamCity は DSL パラメーターを文字列として処理します。 DSL 値をセキュアとしてマークするには、それを パスワード 型のパラメーターに割り当てることができます。

params {
    password("<parameter_name>", "credentialsJSON:<token>")
}

ここで、 <パラメーター名> は DSL からセキュア値にアクセスするためのキーとして使用できる一意の名前です (たとえば、ファイルコンテンツ置換ビルド機能内)。 <トークン> は対象のセキュア値に対応するトークンです。

例:

params {
    password("pass-to-bucket", "credentialsJSON:12a3b456-c7de-890f-123g-4hi567890123")
}

複数の設定ファイルが競合する問題の解決法

プロジェクトが設定ファイルを保存するパスに、同じ名前のファイルを持つサブモジュールが含まれている場合 ...

MainModule:
    - pom.xml
    - settings.kts
    - SubModule:
        - pom.xml
        - settings.kts

   

...TeamCity はこれを競合すると認識し、"複数の settings.kts ファイルの混在" と "JVM の重複クラス名 Settings" 例外を発生させます。この問題を解決するには、 teamcity.internal.dsl.settingsKts.packageName パラメーターでカスタムパッケージ名を指定してください。このパラメーターは複数の場所で設定する必要があります。

メインモジュールの pom.xml ファイル内。

<internalProperties>
    <teamcity.internal.dsl.settingsKts.packageName>
        MainModule
    </teamcity.internal.dsl.settingsKts.packageName>
</internalProperties>

   

同じモジュールの settings.kts ファイル内。

package MainModule
// ...
project {
   params {
      param("teamcity.internal.dsl.settingsKts.packageName", "MainModule")
// ...

   

TeamCity UI から構成パラメーターを追加し、更新された settings.kts ファイルと一致させます。

詳細については、次のチケットを参照してください: TW-93903(英語)。

FAQ とよくある問題

ポータブル DSL ですべての ID に同じプレフィックスが必要な理由

テンプレート、ビルド構成、VCS ルートには、サーバー上のすべての TeamCity プロジェクト全体で一意の IDがあります。これらの ID は通常、 <親プロジェクト ID>_<エンティティ ID> のようになります。

これらの ID は一意である必要があるため、システム内に同じ ID を持つ 2 つの異なるエンティティが存在することはできません。

ただし、ポータブル DSL がポータブルと呼ばれる理由の 1 つは、同じ settings.kts スクリプトを使用して、同じサーバー上でも 2 つの異なるプロジェクトの設定を生成できるためです。
ID の一意性を克服しながらこれを実現するため、TeamCity はポータブル DSL スクリプトで相対 ID を使用します。これらの相対 ID には、親プロジェクト ID のプレフィックスが含まれていません。そのため、TeamCity がポータブル Kotlin DSL スクリプトを生成するときは、生成されたすべてのエンティティの ID から親プロジェクト ID のプレフィックスを削除する必要があります。

ただし、すべてのプロジェクトエンティティの ID にこの接頭辞が含まれていない場合、これは機能しません。この場合、次のエラーが表示される可能性があります。

ビルド構成 ID '<何らかの ID>' には、その親プロジェクト ID に対応するプレフィックスが必要です: '<親プロジェクト ID>'

この問題を修正するには、影響を受けるエンティティの ID を変更します。そのような ID が多数ある場合は、 ID を一括編集プロジェクトアクションを使用して、それらすべてを一度に変更します。

DSL 設定から補助スクリプトにアクセスする方法

設定ファイルをきちんと保つために、長いコード命令を別々のファイルに保存すると便利です。このような補助スクリプトは、設定ファイルと一緒に .teamcity ディレクトリに配置できます。それらの相対パスで参照できます。

例: settings.kts のこの部分は、入力時に受け取ったファイルの内容を読み取る関数 readScript を持つオブジェクトを作成します。

object Util {
    fun readScript(path: String): String {
        val bufferedReader: BufferedReader = File(path).bufferedReader()
        return bufferedReader.use{ it.readText() }.trimIndent()
    }
}

   

ビルドステップでは、この関数を呼び出すため、 .teamcity ディレクトリにある スクリプト\test.sh ファイルを読み取ります。

object CommandLineRunnerTest : BuildType({
    name = "Command Line Runner Test"
    steps {
        script {
            name = "Imported from a file"
            scriptContent = Util.readScript("scripts\\test.sh")
        }
    }
})

   

その結果、コマンドラインビルドステップは、 スクリプト\test.sh で指定された本文でカスタムスクリプトを実行します。

特殊文字の使用方法

スクリプトランナー (コマンドライン、 PowerShell、 Python など) 用に Kotlin DSL を作成する場合は、スクリプトで使用される特殊文字が Kotlin DSL 構文と競合する可能性があることに注意してください。これらの潜在的な問題は、ほとんどの場合、次のカテゴリのいずれかに当てはまります。

Kotlin ガイドライン(英語)で要求されている特殊文字をエスケープしていません。例: echo $(date +"%A") シェルコマンドは Kotlin 構文規則と競合しないため、Kotlin DSL でそのまま使用できます。
script { id = "simpleRunner" scriptContent = """ #... echo $(date +"%A") """.trimIndent() }
ただし、エスケープしないと、変数を直接参照すると、「Kotlin DSL コンパイルエラー: 未解決の参照」というビルドログメッセージが表示されます。
script { id = "simpleRunner" scriptContent = """ day_of_week=Monday echo $day_of_week // Compilation error echo ${'$'}day_of_week // No compilation error, returns "Monday" """.trimIndent() }
% 文字をエスケープしません。 TeamCity は、このようなエスケープされていない文字列をビルドパラメーターへの参照として解釈する場合があります。パーセント文字をエスケープするには、それを 2 回繰り返します (%%)。
例: 次の Kotlin DSL は、2 つのパーセント文字 (%%正規表現%%) を 1 つのパーセント文字 (%\正規表現%) に置き換えると、互換性のあるエージェントのない構成を生成します。
script { name = "Bash script" scriptContent = """ //... set "regex=[0-9]+[.][0-9][0-9](.1)? EAP" set "items=" for /r "$tcInstallDir" %%i in (*) do ( findstr /r "%\%regex%%" "%%i" >nul 2>nul if errorlevel 1 ( set "items=1" ) ) //... """ }

設定 VCS ルートの新しい URL (非ポータブル形式)

問題: Kotlin で設定が保存されている VCS ルートの URL を変更したところ、TeamCity は新しい場所のリポジトリで設定を見つけられなくなりました。

解決:

バージョン管理で Kotlin DSL の URL を修正し、修正をプッシュします。
UI を有効にするには、バージョン対応設定を無効にします。
UI の VCS ルートの URL を修正してください。
同じ VCS ルートと Kotlin 形式のバージョン対応設定を有効にします。 TeamCity は、リポジトリに .teamcity ディレクトリが含まれていることを検出し、設定をインポートするかどうかを確認します。
設定をインポートすることを選択します。

Kotlin DSL でファイルを読み取る方法

問題: .teamcity ディレクトリ内の VCS にある何らかのファイルのデータに基づいて、TeamCity ビルド構成を生成したいと考えています。

解決策:
たとえば、 DslContext.baseDir プロパティを使用して、DSL スクリプトから .teamcity ディレクトリの場所にアクセスできます。

val dataFile = File(DslContext.baseDir, "data/setup.xml")

2019.2 以降、TeamCity は DSL スクリプトの現在の作業ディレクトリが .teamcity ディレクトリと同じであることを保証しなくなったため、これが推奨されるアプローチです。

2019.2 の前は、次のコードを使用できました。

val dataFile = File("data/setup.xml")

プロジェクトとビルド構成の順序を変更する方法

DSL 経由でプロジェクト内のサブプロジェクトの順序を変更したり、構成をビルドしたりするには、それぞれの UI オプションと同様に、そのリストをそれぞれ subProjectsOrder または buildTypesOrder に渡します。例:

project {
    buildType(BuildA)
    buildType(BuildB)
    buildType(BuildC)
    buildTypesOrder = arrayListOf(BuildC, BuildA, BuildB)
}

object BuildA: buildType ({
...
})

object BuildB: buildType ({
...
})

object BuildC: buildType ({
...
})

   

これらの設定を使用すると、ビルド構成が C、A、B の順序で UI に表示されます。

.kts ファイルを分割する方法

サーバー上のすべてのプロジェクトの設定を記述する 1 つの .kts ファイルを維持するのは困難な場合があります。次の 2 つの場合に、このようなファイルが作成される可能性があります。

このファイルは TeamCity によって生成されました。アクション | Kotlin フォーマットで設定をダウンロード… メニューからプロジェクト設定をエクスポートすると、TeamCity はまず、現在のエンティティ (プロジェクト、構成、ルート) の数を計算します。この数が 20 未満の場合、TeamCity は 1 つの .kts ファイルを書き込みます。それ以外の場合は、プロジェクトごとに個別の .kt ファイルを含む複数のフォルダーが作成されます。
ファイルは手動で作成されました。単一の .kts ファイルから始めて新しいプロジェクトを追加し続けると、時間の経過とともにファイルが大きくなりすぎて管理できなくなる可能性があります。

最初のケースでは、ビルドサーバーが 20 エンティティを超えると、TeamCity は設定を自動的に分割します。手動で作成した .kts ファイルの場合は、次のように分割できます。

.teamcity
  └─── pom.xml
  └─── settings.kts   # Stores only the Kotlin DSL version and the "project(_Self.Project)" line
  └─── _Self
         └─── ...
         └─── ...
  └─── ProjectA
         └─── ...
         └─── ...
  └─── ProjectA_Subproject1
         └─── ...
         └─── ...
  └─── ProjectA_Subproject2
         └─── ...
         └─── ...
  └─── ProjectB
         └─── ...
         └─── ...
  └───...
  └───...

   

各フォルダー (<ルート>プロジェクト用の "_Self" フォルダーを含む) は次の構造になっています。

ProjectA
  └─── Project.kt   # Stores a list of subprojects, parameters, connections, and other project-level settings
  └─── buildTypes   # A folder with .kt files that define build configurations, their steps, triggers, build features, and more
          └─── ProjectA_MyBuildConfig1.kt
          └─── ProjectA_MyBuildConfig2.kt 
  └─── vcsRoots     # A folder with .kt files that define VCS roots (for example, custom GitVcsRoot class descendants)
          └─── ProjectA_MyRoot1.kt
          └─── ProjectA_MyRoot2.kt

   

TW-64768(英語) チケットに添付されている ZIP アーカイブをダウンロードして、サンプルを階層的にインスペクションし、個々の .kt ファイルに通常どのようなコンテンツが保存されているかを確認できます。

Kotlin DSL スクリプトをテストする方法

Kotlin スクリプトは、JUnit などの通常のテストフレームワークを使用してテストできます。詳細については、ブログ投稿コードとしての構成、パート 6: 構成スクリプトのテスト(英語)を参照してください。

Kotlin DSL API ドキュメントはまだ初期化されていません

問題:

Teamcity サーバーの アプリ/dsl-ドキュメント/インデックス.html に「Kotlin DSL API ドキュメントはまだ初期化されていません」と表示される
TeamCity 起動中の OutOfMemoryError と、スタックトレース内の org.jetbrains.dokka

ソリューション: 内部プロパティteamcity.kotlinConfigsDsl.docsGenerationXmx=1500m を設定し、サーバーを再起動します。

OutOfMemory エラー

問題: Kotlin DSL 設定の同期が「コンパイルエラー」で失敗する: java.lang.OutOfMemoryError: 「Java ヒープスペース」エラーが teamcity-versioned-settings.log ファイルに書き込まれました。

解決策: 設定ジェネレーターのメモリ制限を引き上げます。デフォルトでは 512m です。 DSL がコンパイルされる場所に関係なく、この制限を 1g (一ギガバイト) 以上に、バージョン管理された設定の pom.xml ファイルで設定します：

<plugin>
    <groupId>org.jetbrains.teamcity</groupId>
    <artifactId>teamcity-configs-maven-plugin</artifactId>
    <version>${teamcity.dsl.version}</version>
    <configuration>
        <format>kotlin</format>
        <dstDir>target/generated-configs</dstDir>
        <internalProperties>
            <teamcity.versionedSettings.configsGeneratorXmx>1g</teamcity.versionedSettings.configsGeneratorXmx>
        </internalProperties>
    </configuration>
</plugin>

   

エージェント側のコンパイルでは、この変更だけで十分です。 DSL がサーバー上でコンパイルされる場合は、同じ teamcity.versionedSettings.configsGeneratorXmx 値を内部プロパティとして設定し、サーバーを再起動する必要もあります。

2026 年 9 月 11 日