バージョン管理でのプロジェクト設定の保存

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 プロジェクト設定を別のリポジトリに保存すると、信頼できないサードパーティーがプロジェクトを変更できなくなります。このリポジトリを非公開にして、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
<project settings directory> /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 は不足している構成を自動的に生成し、更新された依存関係を解決できるため、これらのカスタムブランチ設定を適用できるようになります。

安全な設定の保存

セキュリティデータは VCS の外部に保存することをお勧めします。双方向同期が有効になっている場合、パスワードと API トークンを VCS の外部に保存するオプションはプロジェクト設定 | バージョン設定 | 構成ページで使用できます。デフォルトでは、バージョン設定がプロジェクトで初めて有効になった場合はこのオプションが有効になり、VCS にすでに設定を保存しているプロジェクトの場合は無効になります。

このオプションを有効にすると、TeamCity は、ランダムに生成された ID を、スクランブルされたパスワードの代わりに XML 構成ファイルに保管します。実際のパスワードは TeamCity データディレクトリのディスクに保存され、バージョン管理システムにはチェックインされません。

トークンの管理

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 に設定を保存する必要があります。
あるいは、セキュリティ値を持つパスワードパラメーターを追加し、ネストされたプロジェクトで %parameterName% 参照を使用することもできます。

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 プロバイダーを Terraform 構成に追加します。

詳細:

設定形式

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

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

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

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

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

TeamCity が設定を VCS にコミットする場合、コミッターとして TeamCity ユーザー、および設定が変更されたプロジェクトを示す標準のコミットメッセージを使用します。teamcity.versionedSettings.commitMessagePrefix 内部プロパティを介して、TeamCity によってコミットされた各設定の変更に固定のカスタム接頭辞 (例: teamcity.versionedSettings.commitMessagePrefix=TC Change\n\n) を追加できます。

変更の表示

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

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

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

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

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

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

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

2026 年 3 月 08 日