プロジェクト設定をバージョン管理に保存する

TeamCity では、プロジェクト設定をバージョン管理リポジトリ (VCS) と同期できます。サポートされている VCS は、Git、Mercurial、Perforce、Subversion、Azure DevOps Server（旧 TFS）です。

プロジェクト設定を XML 形式または Kotlin 言語(英語)で保存し、 Kotlin ベースの DSL を使用してプログラムで設定を定義できます。

ビルド構成が、信頼されていないユーザーがコミットをプッシュしたり、プル (マージ) リクエストを作成したりできるリポジトリを対象としている場合は、これらの変更を含むビルドを自動的に実行する VCS トリガーおよび / またはプルリクエストのビルド機能を構成しないでください。代わりに、受信した変更をインスペクションして検証した後、手動で新しいビルドを開始してください。そうしないと、TeamCity はこれらの変更で導入された悪意のあるコードを実行する可能性があります (たとえば、ソースコードから送信されたサービスメッセージを処理したり、改変されたプロジェクト設定を、変更されたプロジェクト設定ディレクトリファイルから適用したりします)。

リポジトリコードを変更できるユーザーによって発生する可能性がある損害の詳細については、このセクションを参照してください: セキュリティノート。

鍵となるポイント

この機能は何をしますか？
個々のプロジェクトの設定を XML または Kotlin 形式でリモートリポジトリに保存できます。

バージョン管理された設定には何が含まれますか？
バージョン管理された設定には、プロジェクトおよびビルド構成に関連するすべてのプロパティが保存されます。サーバー全体のグローバル設定は、専用の TeamCity プロバイダーを使用して HashiCorp Terraform 経由で保存および管理できます。

プロジェクト設定はソースファイルと同じリポジトリに保存されますか？
プロジェクト設定は、アプリケーションソースをホストする同じリポジトリに保存することも、完全に別のリポジトリに保存することもできます。

バージョン管理された設定が有効化されたプロジェクトは編集可能なままですか？
プロジェクトを TeamCity UI 経由で編集可能にするか (この場合、TeamCity は UI で行われた編集をリモートに保存された設定と同期します)、VCS 側の設定ファイルを変更した場合にのみ編集可能にするかを選択できます。

別々のプロジェクトブランチに異なる設定を適用できますか？
はい、異なるリポジトリブランチは異なるプロジェクト設定を保存できます。

UI で設定を変更した後、ビルドが実行されるまでに遅延があるのはなぜですか？
UI 経由で設定が変更されると、TeamCity は VCS へのコミットによって変更が完了するのを待ってから、最新の変更を含むビルドを実行します。

変更の作成者は誰ですか？
ユーザーインターフェース経由で設定を変更した場合、Git および Mercurial では、実際に UI 経由で変更を行ったユーザーに代わって VCS へのコミットが実行されます。 Perforce と Azure DevOps Server (旧 TFS) では、VCS ルートに指定されたユーザーの名前が使用され、Subversion では、コミットメッセージに実際に UI 経由で変更を行った TeamCity ユーザーのユーザー名も含まれます。

VCS との設定の同期

デフォルトでは、プロジェクト設定とバージョン管理システムとの同期は無効になっています。

有効にするには、プロジェクト設定 | バージョン対応設定 | 構成に移動します。「バージョン設定の有効化 / 無効化」権限が必要です (システム管理者ロールのデフォルト)。

このページでは、次のいずれかのオプションを選択できます。

親プロジェクトと同じ設定を使用します（デフォルト）。
同期を無効にします。
同期を有効にします。この場合、ビルドの開始時に使用する設定を定義することもできます。以下の詳細を参照してください。

同期が有効になっている場合は、 two-way モードまたは one-way モードのいずれかで動作できます。

デフォルトモードは双方向同期です。このモードは、 UI 経由でプロジェクト設定を編集できるようにするオプションがチェックされている場合に有効になります。

双方向同期は次のように機能します。

TeamCity UI のプロジェクト設定に加えられた管理上の各変更は、バージョン管理システムにコミットされます。コミットされた変更の作成者は、関連するプロジェクト編集を行った TeamCity ユーザーと一致します。
変更が VCS 側で適用された場合 (Kotlin または XML 設定ファイルが編集された場合)、TeamCity サーバーはそれらを検出し、その場でプロジェクトを変更します。
新しくチェックインされた設定を適用する前に、TeamCity はそれらを検証します。検証に失敗した場合 (たとえば、ビルド構成が存在しない VCS ルートを参照している場合や、重複した ID がある場合)、現在のプロジェクト設定はそのまま残され、UI にエラーが表示されます。

UI 経由でプロジェクト設定を編集できるようにするオプションを無効にすると、プロジェクト設定は UI で読み取り専用になり、VCS 側で行われた変更のみが反映されます。これは、プロジェクト設定をコードとして定義したり、読み取り専用の VCS ブランチから設定をロードしたりする場合に役立ちます。

プロジェクトの同期を有効にすると、デフォルトの「親プロジェクトの設定を使用する」オプションが選択され、そのすべてのサブプロジェクトでも同期が有効になります。 TeamCity は、 SSH 鍵を除き、プロジェクト設定に対するすべての変更 (ビルド構成、テンプレート、 VCS ルートなどの変更を含む) を同期します。個々のサブプロジェクトを同期から除外するには、サブプロジェクトを同期が無効ですモードに切り替えます。

設定の同期を有効化するとすぐに、TeamCity は現在のプロジェクトツリーとサーバー設定をリモートリポジトリにコミットします。ターゲットの場所にプロジェクト設定がすでに保存されている場合は、警告が表示されます。この警告では、TeamCity が次の操作を行うかどうかを選択できます：

VCS 内の設定を TeamCity サーバー上の現在のプロジェクト設定で上書きする (双方向同期が有効な場合のみ)。または
VCS から設定をインポートし、TeamCity サーバー上の現在のプロジェクト設定をバージョン管理からの設定に置き換える。

設定場所の選択

TeamCity プロジェクト設定のデフォルトの場所は、ターゲットプロジェクトを保存している同じリポジトリのルートにある .teamcity フォルダーです。ワークフローの詳細とビジネスニーズによっては、このデフォルトの設定がチームにとって最適ではない場合があります。

たとえば、スタンドアロンのマイクロサービスと外部ライブラリが隣接するディレクトリでホストされているモノレポで作業するチームは、設定を別々のディレクトリに保存する個別の TeamCity プロジェクトをセットアップしたい場合があります。プロジェクトごとにカスタム設定ディレクトリを使用すると、同じモノレポをターゲットとするプロジェクトが互いの設定を常に上書きすることがなくなります。

実装したい別のシナリオとして、TeamCity 固有のファイルをソースから移動することが考えられます。このアプローチにより、CI/CD エコシステムの詳細がわかりにくくなり、外部の関係者から見えなくなります。さらに、TeamCity サーバー全体の設定を保存する専用の VCS リポジトリ (各プロジェクトには設定を保存するための独自のリポジトリフォルダーがあります) を用意することも、設定のメンテナンスとテストに役立つ場合があります。

これらのタスクまたは同様のタスクを実装するには、プロジェクト設定 VCS ルートおよび VCS 内の設定パス設定を使用します。

別個の VCS ルート

プロジェクト設定 VCS ルートセレクターでは、TeamCity がプロジェクト設定の取得とコミットに使用する VCS ルートの構成を選択できます。このプロジェクトが直接所有するルート、またはその親プロジェクトのいずれかが所有するルートを選択できます。

VCS ルートはリモートリポジトリへの接続を定義するため、ルートを選択するということは、プロジェクト設定を保存するリポジトリを選択することを意味します。

コードの変更を取得してソースファイルをチェックアウトするルートと同じルートを使用すると、プロジェクト設定はアプリケーションと同じリポジトリに保存されます。 TeamCity 設定をソースファイルと並べて保持したい場合は、このセットアップを使用します。
設定の同期に別のルートを使用すると、プロジェクト設定を別のリポジトリに移動できます。 TeamCity プロジェクト設定を別のリポジトリに保存することで、信頼されていない第三者にプロジェクトを変更されないようにできるため、この方法は 3rd-party コントリビューターがいる公開リポジトリに有益な場合があります。このリポジトリを非公開にして、CI/CD セットアップの内部動作をさらに隠すことができます。

プロジェクト設定 VCS ルートコンボボックスでは新しいルートを作成できないことに注意してください。バージョン対応設定ページで使用を開始する前に、プロジェクト設定の VCS ルートタブに移動して必要なルートを設定する必要があります。

カスタム設定パス

VCS 内の設定パスオプションを使用すると、プロジェクト設定を保存するディレクトリへのパスを手動で指定できます。

デフォルトの .teamcity 値を任意のカスタムパス (たとえば、 .teamcity-settings/accounting) またはピリオド (。) に変更できます。後者を使用すると、設定をリポジトリルートに直接保存できます。

あいまいな設定ソースによって発生する予期しないエラーを防ぐため、同期がすでにアクティブな場合、TeamCity では設定パスを変更できません。このパスを変更するには、同期を無効にして設定を保存し、再度有効にして必要なディレクトリを指定します。

新しいプロジェクトを作成する際、TeamCity は現在、既存のプロジェクト設定がデフォルトの .teamcity フォルダーに保存されている場合にのみ検出します。プロジェクト設定がカスタムリポジトリディレクトリに保存されている場合、TeamCity はこれらの設定をインポートしたり、新しいプロジェクトを最初から開始したりするオプションを提供しません。回避策として、次の操作を行います。

リモートリポジトリから新しいプロジェクトを作成します。
プロジェクト設定に移動し、バージョン対応設定ページで同期を有効にします。
VCS 内の設定パスフィールドに既存のプロジェクト設定へのパスを指定します。
設定を保存するには適用をクリックし、ページの下部にある VCS からプロジェクト設定を読み込む… をクリックします。

ビルドに適用する設定の定義

TeamCity がビルドを開始する必要がある場合、次の 2 つの設定のいずれかを適用できます:

TeamCity サーバー上の現在の設定。これらは、TeamCity UI 経由、または VCS のプロジェクト設定ディレクトリへのコミット経由でサーバーに適用された最新の変更をすべて含む設定です。
VCS に保存されているカスタム設定。これらは、デフォルト以外のブランチまたはビルド用に選択された特定のリビジョンに保存されているプロジェクト設定ディレクトリの設定です。

これら 2 つの設定のどちらを適用するかを選択できるため、次のオプションが許可されます。

プロジェクト設定ディレクトリに、異なる設定を持つ複数のブランチを用意します。つまり、ブランチ A には、ブランチ B とは異なるパラメーター、ステップ、ビルド機能、アーティファクト公開ルール、チェーン設定を含めることができます。
プロジェクト設定ディレクトリで行われた変更を使用して個人ビルドを開始すると、これらの変更がビルドの動作に影響します。
履歴ビルドにさらに柔軟性を加えます。 TeamCity はまず、選択された変更の時点に対応する設定を使用しようとします。それ以外の場合は、現在のプロジェクト設定が使用されます。

ビルドの開始時に TeamCity が適用する設定を指定するには、管理 | <プロジェクト> バージョン対応設定ページで必要なオプションを選択します。

常に現在の設定を使用する - すべてのビルドは、TeamCity サーバーの現在のプロジェクト設定を使用します。ブランチ、履歴、個人ビルドでの設定の変更は無視されます。ユーザーは、カスタムプロジェクト設定でビルドを実行することはできません。
デフォルトで現在の設定を使用する - 通常のビルドは、TeamCity サーバーの最新のプロジェクト設定を使用します。ユーザーは、VCS からインポートした設定でカスタムビルドを実行できます。
VCS の設定を使用する - VCS からの設定を使用するすべてのブランチビルドと履歴ビルドは、ビルド用に計算されたバージョン設定のリビジョンから設定を読み込みます。ユーザーは、 IDE からの個人ビルドで構成設定を変更したり、カスタムビルドダイアログを使用して TeamCity サーバー上の現在のプロジェクト設定でビルドを実行したりできます。

特定の設定は VCS からロードできません。 TeamCity がこれらの設定の編集を検出すると、それらを無視し、代わりにサーバーに保存されている現在の設定を適用します。これらの設定は次のとおりです。

ビルドトリガー
ハングしたビルドの検出、個人用ビルドの可用性、ビルド構成タイプなどのビルド構成レベルのオプション
クリーンアップ規則
カスタム実行におけるエージェントの要件
特定のビルド機能の設定 (たとえば、コミットステータスパブリッシャーは VCS 設定を使用しますが、プルリクエストは常に現在のサーバー設定を使用します)
既存のアーティファクトルールの編集 (新しいルールを追加したり、既存のルールを削除したりすることもできます)
(スナップショット依存関係とバージョン管理設定の変更を適用設定が無効な場合のみ) 新しいスナップショット依存関係、チェックアウトルール、VCS ルートの作成、および既存のものの編集。

例: ブランチ固有の設定

選択した VCS で空のリポジトリを作成して初期化します。この例では、GitHub.com のリポジトリが使用されます。
このリポジトリから新しい TeamCity プロジェクトを作成します。
Python ランナーをビルド構成に追加します。
import jetbrains.buildServer.configs.kotlin.* import jetbrains.buildServer.configs.kotlin.buildSteps.python object Build : BuildType({ name = "Build" // ... steps { python { id = "python_runner" command = script { content = """print ("Running a Python script...")""" } } } // ... })
プロジェクト設定を開き、 バージョン管理された設定設定タブに移動します。
次のオプションを選択します。
- 同期が有効化されています: オン
- プロジェクト設定 VCS ルート: プロジェクトの VCS ルートを選択します
- 設定フォーマット: Kotlin
- ビルド開始時: 「VCS の設定を使用する」を選択します
- スナップショット依存関係とバージョン管理設定の変更を適用する: オン (スナップショット依存関係とバージョン管理設定の変更を適用セクションを参照)
新しい設定を保存するには、適用をクリックします。 TeamCity はビルド構成の有効性を検証し、設定を含むプロジェクト設定ディレクトリを関連する VCS リポジトリにプッシュします。
リモートリポジトリからローカルストレージに TeamCity 設定をクローンします。
git clone <Clone_URL> .
新しいリポジトリブランチを作成します。
git checkout -b custom-branch
<プロジェクト設定ディレクトリ>/settings.kts (デフォルトでは .teamcity/settings.kts) ファイルのローカルコピーを次のように編集します。
import jetbrains.buildServer.configs.kotlin.* import jetbrains.buildServer.configs.kotlin.buildSteps.csharpScript object Build : BuildType({ name = "Build" // ... steps { csharpScript { id = "csharpScript" content = """Console.WriteLine("Running a CSharp script...");""" tool = "%teamcity.tool.TeamCity.csi.DEFAULT%" } } // ... })
新しいブランチをリモートリポジトリにプッシュします。
git add * git commit -a -m "Modify custom-branch settings" git push --set-upstream origin custom-branch
TeamCity はまもなく新しい変更を収集します。プロジェクト設定ページのバージョン対応設定タブで VCS からプロジェクト設定を読み込む… をクリックすると、このプロセスを手動でトリガーできます。
リモートリポジトリが変更されるたびに新しいビルドを起動するようにデフォルトのトリガーを設定している場合は、新しいカスタムブランチの新しいビルドが自動的に開始されます。それ以外の場合は、ビルド構成ページで必要なブランチを選択し、新しいビルドを手動で実行します。

その結果、ビルド構成は、実行されるブランチビルドに応じて異なるアクション (メインブランチの場合は Python スクリプト、カスタムブランチの場合は C# スクリプト) を実行するようになります。ブランチ設定間にさらに違いを追加してブランチビルドを実行し、TeamCity が settings.kts ファイルの異なるバージョンをどのように処理するかを試すことができます。

スナップショット依存関係とバージョン管理設定の変更を適用

プロジェクトのバージョン対応設定ページで対応するオプションが無効化されている場合、TeamCity は以下に対する編集を無視します：

スナップショットの依存関係
チェックアウトのルール
VCS ルート

これは、既存の依存関係、チェックアウトルール、ルートの編集と新しい依存関係の作成の両方に適用されます。

例: 次の Kotlin サンプルは、同じプロジェクトの 2 つの設定バージョンを示しています。

メイン (デフォルト) ブランチは、単一の BC0 → BC3 → BC5 ビルドチェーンにリンクされた 3 つのビルド構成を定義します。各構成は「output.txt」ファイルを編集し、次の構成に渡します。
カスタムブランチは、オリジナルのチェーンを 2 つの新しい構成 (BC0 → BC2 → BC3 → BC4 → BC5) で拡張します。

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

project {
    buildType(BC0)
    buildType(BC3)
    buildType(BC5)
}

// 1st build configuration
object BC0 : BuildType({
    name = "BC0"
    artifactRules = "output.txt"
    steps {
        script {
            name = "Prepare File"
            id = "Prepare_File"
            scriptContent = """
                rm output.txt
                touch output.txt
            """.trimIndent()
        }
        script {
            name = "WriteLine"
            id = "WriteLine0"
            scriptContent = """echo "Running BC0 config" > output.txt"""
        }
    }
    // ...
})

// 2nd build configuration
object BC3 : BuildType({
    name = "BC3"
    artifactRules = "output.txt"
    steps {
        script {
            name = "WriteLine"
            id = "WriteLine3"
            scriptContent = """echo "Running BC3 config" >> output.txt"""
        }
    }
    dependencies {
        dependency(BC0) {
            snapshot { reuseBuilds = ReuseBuilds.NO }
            artifacts { artifactRules = "output.txt" }
        }
    }
    // ...
})

// 3rd build configuration
object BC5 : BuildType({
    name = "BC5"
    artifactRules = "output.txt"
    steps {
        script {
            name = "WriteLine"
            id = "WriteLine5"
            scriptContent = """echo "Running BC5 config" >> output.txt"""
        }
    }
    dependencies {
        dependency(BC3) {
            snapshot { reuseBuilds = ReuseBuilds.NO }
            artifacts { artifactRules = "output.txt" }
        }
    }
    // ...
})

     

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

project {
    buildType(BC0)
    buildType(BC2)
    buildType(BC3)
    buildType(BC4)
    buildType(BC5)
}

// 1st build config
object BC0 : BuildType({
    name = "BC0"
    artifactRules = "output.txt"
    steps {
        script {
            name = "Prepare File"
            id = "Prepare_File"
            scriptContent = """
                rm output.txt
                touch output.txt
            """.trimIndent()
        }
        script {
            name = "WriteLine"
            id = "WriteLine0"
            scriptContent = """echo "Running BC5 config" > output.txt"""
        }
    }
    // ...
})

// 2nd build config
object BC2 : BuildType({
    name = "BC2"
    artifactRules = "output.txt"
    steps {
        script {
            name = "WriteLine"
            id = "WriteLine2"
            scriptContent = """echo "Running virtual BC2 config" >> output.txt"""
        }
    }
    dependencies {
        dependency(BC0) {
            snapshot { reuseBuilds = ReuseBuilds.NO }
            artifacts { artifactRules = "output.txt" }
        }
    }
    // ...
})

// 3rd build config
object BC3 : BuildType({
    name = "BC3"
    artifactRules = "output.txt"
    steps {
        script {
            name = "WriteLine"
            id = "WriteLine3"
            scriptContent = """echo "Running BC3 config" >> output.txt"""
        }
    }
    dependencies {
        dependency(BC2) {
            snapshot { reuseBuilds = ReuseBuilds.NO }
            artifacts { artifactRules = "output.txt" }
        }
    }
    // ...
})

// 4th build config
object BC4 : BuildType({
    name = "BC4"
    artifactRules = "output.txt"
    steps {
        script {
            name = "WriteLine"
            id = "WriteLine4"
            scriptContent = """echo "Running virtual BC4 config" >> output.txt"""
        }
    }
    dependencies {
        dependency(BC3) {
            snapshot { reuseBuilds = ReuseBuilds.NO }
            artifacts { artifactRules = "output.txt" }
        }
    }
    // ...
})

// 5th build config
object BC5 : BuildType({
    name = "BC5"
    artifactRules = "output.txt"
    steps {
        script {
            name = "WriteLine"
            id = "WriteLine5"
            scriptContent = """echo "Running BC5 config" >> output.txt"""
        }
    }
    dependencies {
        dependency(BC4) {
            snapshot { reuseBuilds = ReuseBuilds.NO }
            artifacts { artifactRules = "output.txt" }
        }
    }
    // ...
})

     

スナップショット依存関係とバージョン管理設定の変更を適用するオプションを無効にして、カスタムブランチのビルドを実行しようとすると、「アーティファクトの依存関係を解決できませんでした」というエラーで失敗します。これは、スナップショットの依存関係に対する編集が無視されるために発生します。 TeamCity の観点では、このセットアップは存在しない構成を必要とするため無効です。

前述の設定により、TeamCity は不足している構成を自動的に生成し、更新された依存関係を解決できるため、これらのカスタムブランチ設定を適用できるようになります。

セキュア設定の保存

パスワードと API トークンを VCS の外部に保存するオプションは、プロジェクト設定 | バージョン対応設定 | 構成ページで利用でき、パスワードと API トークンの保存方法を選択できます：

有効化 (推奨): TeamCity は、スクランブルされたパスワードの代わりに、ランダムに生成された ID を XML 構成ファイルに保存します。実際のパスワードは、 TeamCity データディレクトリ配下のディスクに保存され、バージョン管理システムにはチェックインされません。
無効: TeamCity は暗号化キーを使用して機密データをスクランブルします。この動作を選択する場合は、セキュリティ上の影響に注意してください。

セキュリティ上の理由により、TeamCity 2026.2 以降のバージョンでは、このオプションは、パスワードをスクランブルされた形式で VCS に保持している既存のプロジェクトでのみ使用できます。その他のプロジェクトでは、この設定は最も安全なオプションとして自動的に有効化されます。

トークンの管理

TeamCity UI 経由ではなく (たとえば、Kotlin DSL 経由で)、バージョン管理された設定にパスワード (またはその他の安全な値) を追加する必要がある場合は、このパスワードの代わりに設定で使用するトークンを生成できます。

プロジェクト設定で、安全な値のトークンを生成をアクションドロップダウンメニューで選択します。
パスワードを入力してトークンを生成をクリックします。
生成されたトークンはサーバー上に保存されます。これで、パスワードの代わりにそれをコピーしてプロジェクト構成ファイルに使用できるようになります。
params { password("<parameter_name>", "credentialsJSON:<token>") }
トークンは、構成ファイル内の安全な値を参照するためにのみ使用できます。 TeamCity UI でパスワードパラメーターの値として「credentialsJSON:<token>」を挿入しても、TeamCity はトークンの基になるセキュアな値を取得しません。代わりに、「credentialsJSON:<token>」文字列自体が実際のパスワード値として使用されます。

プロジェクトバージョン対応設定セクションのトークンタブで、新しいセキュアトークンを生成することもできます。このタブは、「VCS の外部に安全な値を保存する」オプションが有効になっているプロジェクトで使用できます。

トークンタブでは、未使用のトークンを含むすべてのプロジェクトトークンを表示できます。
プロジェクトの安全なデータがバージョン管理システムの外部に保存されている場合、プロジェクトから切り離される可能性があります: たとえば、トークンを含むプロジェクトが階層内の別の場所に移動された場合や、新しい TeamCity サーバー上で DSL から作成された場合です。このような場合、このタブでプロジェクトトークンの値を指定できるため、プロジェクトはそれらを引き続き使用できます。

さらに、編集が許可されている他のプロジェクトで必要なトークンが利用可能な場合、TeamCity はそれらを自動的に見つけます。これらのプロジェクトで使用されている安全な値を現在のプロジェクトにコピーできます。

トークンに使用可能な 1 つ以上の安全な値がある場合、ボタンはこのトークンの反対側に表示されます。クリックして使用可能なプロジェクトを確認し、値のコピー元のプロジェクトを選択してから、コピーをクリックして選択を確認します。

セキュアな値はプロジェクト階層によって継承できます。プロジェクト内の設定 (VCS ルート、OAuth 接続、クラウドプロファイル) にパスワードが必要な場合、このパスワードに対して生成されたトークンは、このプロジェクトおよびその任意のサブプロジェクトで使用できます。継承されたパスワードを使用できるようにするには、サブプロジェクトでバージョン管理された設定を有効化し、親プロジェクトと同じ VCS に設定を保存する必要があります。
または、安全な値を持つパスワードパラメーターを追加し、ネストされたプロジェクトで %\パラメーター名% 参照を使用できます。

セキュリティデータを VCS に保存することの影響

デフォルトのパスワードと API トークンを VCS の外部に保存する設定を無効にする場合は、次の影響を考慮してください。

パスワードとトークンは暗号化されますが、VCS では引き続き利用できます。
- プロジェクト設定がソースコードと同じリポジトリに保存されている場合、リポジトリにアクセスできるユーザーは誰でもこれらの暗号化されたパスワードを見ることができます。
- プロジェクト設定が専用リポジトリでソースコードとは別にに保存され、「ビルドで設定の変更を表示」オプションが有効化されている場合、「VCS ファイルの内容を表示」権限を持つユーザーは、変更差分ビューアーを使用して TeamCity UI ですべての変更を確認できます。
VCS を介して任意の方法で設定を変更できる場合、TeamCity で構成されたビルド構成の権限に関係なく、任意のビルド構成のビルドをトリガーし、任意のビルド構成の設定を取得できます。
間違った設定や悪意のある設定をコミットすることにより、ユーザーはサーバー全体のパフォーマンスや他のユーザーへのサーバーの表示に影響を与える可能性があります。

パスワード、API トークン、その他の安全な設定は、上記の対応するオプションを使用して VCS の外部に保存することをお勧めします。

SSH キーは VCS リポジトリに保存されないことに注意してください。

プロジェクト設定からプロジェクトを作成する

プロジェクト設定をリモートリポジトリに保存するだけでなく、その逆を行うこともできます。Kotlin DSL でプロジェクトや構成を記述し、リポジトリにアップロードして、それを使って新しい TeamCity プロジェクトを作成できます。

以下の手順はプロセスの概要です。

空の TeamCity プロジェクトを作成します。
設定ファイルを保存するリポジトリに接続された VCS ルートを作成します。
プロジェクトバージョン対応設定でこのルートを選択します。
インポートプロセスを開始します。

詳細な手順については、次の記事を参照してください: Kotlin DSL で新しいプロジェクトを作成。

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

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

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

さらに詳しく知る:

設定フォーマット

設定形式を選択できるようにするには、プロジェクト設定 | バージョン対応設定 | 構成で詳細オプションを表示をクリックします。

TeamCity はプロジェクト設定を保存します:

XML 形式
Kotlin ベースの DSL 形式（専用ページを参照）

Kotlin DSL が選択されている場合は、コードを TeamCity サーバーまたはビルドエージェント上で実行するかどうかも選択できます。

現在のプロジェクト設定を VCS にコミット

現在の構成を VCS にコミットする場合 (たとえば、以前に誤って構成された設定をリポジトリにコミットしたため、TeamCity がエラーと警告を表示して読み込めなかった場合)、現在のプロジェクト設定をコミットオプションをバージョン対応設定 | 構成ページで使用できます。

TeamCity が設定を VCS にコミットする場合、TeamCity ユーザーをコミッターとして、また設定が変更されたプロジェクトを記録する標準のコミットメッセージを使用します。 teamcity.versionedSettings.commitMessagePrefix 内部プロパティを介して、TeamCity によってコミットされた各設定変更に固定のカスタムプレフィックスを追加できます。たとえば、 teamcity.versionedSettings.commitMessagePrefix=TC 変更\n\n です。

変更の表示

TeamCity は設定を同期するだけでなく、バージョン管理で通常の変更に対して行うのと同じ方法で、プロジェクト設定への変更も自動的に表示します。影響を受けるビルド構成について、変更を表示するように構成できます: プロジェクト設定 | バージョン対応設定 | 構成タブで詳細オプションを表示をクリックし、ビルドで設定変更を表示チェックボックスをオンにします。このオプションは、現在のビルド構成に直接接続されていない VCS ルートにバージョン設定を保存している場合にのみ有効です。 VCS ルートがこの構成に接続されている場合、特定のビルドトリガールールが構成されていない限り、その変更はデフォルトで表示されます。

バージョン管理された設定をビルド構成に直接接続されているものではなく、別の VCS ルートに保存する場合、このチェックボックスをオンにすると、これらの VCS ルートに加えられた変更が表示され始めます。 VCS ルートがすでに構成に接続されている場合は、何も実行されません。

デフォルトでは、VCS トリガーはそのような変更を無視します。設定のコミットでビルドトリガーを有効にするには、トリガールールを +:ルート=Settings_ルート_id;:* 形式で追加します。

プロジェクト設定が保存されている VCS ルートのすべての変更は、バージョン対応設定 | 変更ログタブにリストされます。

TeamCity アップグレード後にバージョン設定を有効化

XML 設定ファイルのフォーマットは、新機能や改善に対応するため、TeamCity のバージョンごとに変わります。通常、フォーマットはバグ修正リリース内では変更されず、メジャーリリースで変更されます。 TeamCity サーバーがアップグレードされると、TeamCity サーバー上の現在の設定は以前のフォーマットから現在のフォーマットに変更されます。

本番サーバーをアップグレードする前に、本番データを使用して TeamCity テストサーバーをアップグレードするのが一般的です。古いバージョンの本番サーバーで使用されている設定のフォーマットを誤って変更しないように、TeamCity のアップグレード後はバージョン設定が無効になり、対応するヘルス項目が表示されます。システム管理者には、バージョン管理された設定を有効化する権限があります (管理 | サーバーの健全性 | バージョン対応設定の無効化、有効化をクリックします)。有効にすると、現在の TeamCity バージョンのフォーマットに変換された設定がバージョン管理にチェックインされます。新しい設定は VCS ルートのデフォルトブランチにコミットされる点に注意してください。他のブランチに保存されている設定は手動で更新する必要があります。

2026 年 9 月 11 日