Kotlin DSL

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

バージョン管理に保存された 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 がなければ、これらすべての構成を作成するユーザーインターフェースでかなりの時間を費やす必要があります。

Kotlin DSL を始めよう

この Kotlin チュートリアル(英語)は、ほとんどの Kotlin 機能をすばやく学習できます。サーバーの Kotlin DSL API ドキュメントは、<teamcityserver:port>/app/dsl-documentation/index.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 を押します。
プロジェクト設定セクションでモジュールを選択します。
プラス記号をクリックし、モジュールのインポートを選択して、プロジェクト設定を含むディレクトリを選択します。OK をクリックして、ウィザードに従います。
適用をクリックしてください。新しいモジュールがプロジェクト構造に追加されます。

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

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

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

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

ローカル TeamCity サーバーの DSL ドキュメントは、いつでも <TeamCity_server_URL/app/dsl-documentation/index.html で入手できます。このドキュメントを IDE にインポートすることもできます。こうすることで、.kts ファイルを編集するときにオブジェクトの説明と例を表示できるようになります。

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

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

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

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 構成ファイルを生成するために使用できる generate タスクがあります。このタスクは、IDE（Maven ツールウィンドウのプラグイン | teamcity-configs | teamcity-configs: 生成ノードを参照）またはコマンドラインから開始できます。

mvn teamcity-configs:generate

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

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

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

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

Web UI 経由でプロジェクト設定を編集する

TeamCity では、プロジェクト設定が Kotlin DSL に保存されている場合でも、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_Build のビルド構成に追加します。

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 を使用します。この ID を一定に保つことをお勧めします。DSL コードで行われた変更は、TeamCity の各ビルド構成に一貫して適用されます。

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

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

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

UI で DSL を表示する

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

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

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

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

package src.main.kotlin.builds

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

TeamCity で、管理 | DSL ライブラリに移動し、DSL ライブラリをアップロードをクリックします。これにより、.jar ライブラリをアップロードし、オプションの groupId、artifactId、version 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 つは、同じサーバーまたは複数のサーバー上の複数のプロジェクトでスクリプトを使用できることです（名前はポータブルです）。

新しいプロジェクトを作成するときは、TeamCity を、Kotlin DSL 形式でプロジェクト設定を保存するリポジトリにポイントします。TeamCity には、選択できる 3 つのオプションが表示されます。

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

Importing Kotlin settings when creating a project from URL

バージョン 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 コードでコンテキストパラメーターを参照するには、DslContext オブジェクトの getParameter() メソッドを使用します。このパラメーターのデフォルト値をオプションの 2 番目の引数として指定できます。getParameter("<parameter-name>", "<default-value>")
次の例は、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 ファイルに <contextParameters> ブロックを追加します。

コンテキストパラメーターを使用した 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 プロバイダーを Terraform 構成に追加します。

詳細:

拡張トピック

チェーン DSL 拡張機能の構築

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

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

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

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

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

設定の検証

DSL API バージョン v2017_2 + を使用した設定は、TeamCity サーバーでの DSL 実行中に検証されます。generate タスクを使用して 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

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

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

pom.xml
<project id>/settings.kts
<project id>/Project.kt
<project id>/buildTypes/<build conf id>.kt
<project id>/vcsRoots/<vcs root id>.kt

<project 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 を元の値に戻すことです。一方、エンティティの id は、uuid が同じままであれば自由に変更できます。これが、非ポータブル 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 値をセキュアとしてマークするには、それを password 型のパラメーターに割り当てることができます。

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

ここで、<parameter_name> は、DSL を介して安全な値にアクセスするためのキーとして使用できる一意の名前です（たとえば、ファイル内容の置き換えビルド機能で）。<token> は、ターゲットのセキュア値に対応するトークンです。

例:

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 重複クラス名設定」例外を発生させます。この問題を解決するには、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")
// ...

更新された settings.kts ファイルと一致するように、TeamCity UI を介して構成パラメーターを追加します。

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

FAQ とよくある問題

なぜポータブル DSL はすべての ID に同じ接頭辞を必要としますか？

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

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

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

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

ビルド構成 ID '<some 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 ディレクトリにある scripts\test.sh ファイルを読み取ります。

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

その結果、コマンドラインビルドステップは、scripts\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 は、このようなエスケープされていない文字列を build パラメーターへの参照として解釈する場合があります。パーセント文字をエスケープするには、それを 2 回繰り返します (%%)。
例: 次の Kotlin DSL は、2 つのパーセント文字 (%%regex%%) を 1 つのパーセント文字 (%regex%) に置き換えると、互換性のあるエージェントのない構成を生成します。
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
         └─── ...
         └─── ...
  └───...
  └───...

各フォルダー (<Root> プロジェクトの "_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 サーバーの app/dsl-documentation/index.html に「Kotlin DSL API ドキュメントはまだ初期化されていません」と表示される
TeamCity 起動時の OutOfMemoryError とスタックトレースの org.jetbrains.dokka

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

メモリ不足エラー

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

ソリューション : teamcity.versionedSettings.configsGeneratorXmx 内部プロパティを 1g (1 ギガバイト) 以上に設定し、サーバーを再起動します。デフォルトのプロパティ値は 512m です。

2026 年 2 月 18 日

TeamCity オンプレミス 2025.11 ヘルプ

Kotlin DSL

Kotlin DSL の仕組み

Kotlin DSL を始めよう

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

新規プロジェクトの作成

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

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

Kotlin DSL の編集

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

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

Web UI 経由でプロジェクト設定を編集する

パッチの例

ID 変更後のビルド履歴の復元

UI で DSL を表示する

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

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

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

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

拡張トピック

チェーン DSL 拡張機能の構築

設定の検証

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

非携帯 DSL

settings.kts

Project.kt

DSL で安全な値を扱う

複数の設定ファイルの競合の解決

FAQ とよくある問題

なぜポータブル DSL はすべての ID に同じ接頭辞を必要としますか？

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

特殊文字の使用方法

設定 VCS ルートの新しい URL (非ポータブルフォーマット)

Kotlin DSL のファイルの読み方

プロジェクトを並べ替えて構成を構築する方法

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

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

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

メモリ不足エラー

関連ページ：

Kotlin DSL

Kotlin DSL の仕組み

Kotlin DSL を始めよう

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

新規プロジェクトの作成

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

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

Kotlin DSL の編集

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

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

Web UI 経由でプロジェクト設定を編集する

パッチの例

ID 変更後のビルド履歴の復元

UI で DSL を表示する

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

Kotlin DSL スクリプトを共有する

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

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

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

拡張トピック

チェーン DSL 拡張機能の構築

設定の検証

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

非携帯 DSL

settings.kts

Project.kt

DSL で安全な値を扱う

複数の設定ファイルの競合の解決

FAQ とよくある問題

なぜポータブル DSL はすべての ID に同じ接頭辞を必要としますか？

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

特殊文字の使用方法

設定 VCS ルートの新しい URL (非ポータブルフォーマット)

Kotlin DSL のファイルの読み方

プロジェクトを並べ替えて構成を構築する方法

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

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

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

メモリ不足エラー

関連ページ：