TeamCity 2020.1ヘルプ

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

概要

TeamCityを使用すると、プロジェクト設定とバージョン管理リポジトリを双方向で同期できます。サポートされているVCSは、Git、Mercurial、Perforce、Subversion、およびAzure DevOps Server(以前のTFS)です。

XML形式およびKotlin言語(英語)で設定を保存し、kotlinベースのDSLを使用してプログラムで設定を定義できます。

双方向設定の同期を有効にすると:

  • TeamCity Web UIでプロジェクト設定に加えられた各管理上の変更は、バージョン管理にコミットされます。変更は、TeamCityユーザーをコミッターとして注意して行われます。

  • 設定の変更がバージョン管理にコミットされると、TeamCityサーバーは変更を検出し、その場でプロジェクトに適用します。
    新しくチェックインした設定を適用する前に、検証制約が適用されます。制約が満たされていない場合(つまり、設定が無効である場合)、現在の設定はそのまま残り、UIにエラーが表示されます。無効な設定とは、たとえば、存在しないVCSルートを参照するビルド構成、重複したIDまたは重複した名前を持つなどの制約のためにロードできない設定です。

バージョン設定は、TeamCityデータディレクトリと同じ形式で、VCSリポジトリのルートにある .teamcity ディレクトリに保存されます。

VCSとの設定の同期

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

有効にするには、プロジェクト設定 | バージョン対応設定にアクセスしてください。

バージョン設定の有効化/無効化」許可が必要です(システム管理者ロールのデフォルト)。

構成タブを使用して定義する

  • 同期設定が親プロジェクトと同じかどうか。

  • 同期が有効かどうか。
    • 同期が有効になっている場合、ビルドの開始時に使用する設定を定義できます。以下の詳細を参照してください。

  • プロジェクト設定の保存に使用されるVCSルート:ソースコードと同じリポジトリ、または専用のVCSルートのいずれかに設定を保存できます。

プロジェクトの同期を有効にすると、デフォルトの「親プロジェクトの設定を使用する」オプションが選択されたすべてのサブプロジェクトでも同期が有効になります。TeamCityは、SSHキーを除くすべてのプロジェクト設定の変更( ビルド構成テンプレートVCSルートなどの変更を含む)を同期します。
ただし、特定のサブプロジェクトで「同期が無効です」オプションが選択されている場合、このオプションが親プロジェクトで有効になっていても、そのようなサブプロジェクトは同期されません。

プロジェクトで同期が有効になるとすぐに、TeamCityはプロジェクトツリー全体(すべてのサブプロジェクトを含むプロジェクト)の選択されたリポジトリで初期コミットを行い、サーバーからの現在の設定を保存します。特定のプロジェクトの設定が指定されたVCSルート(親プロジェクト設定のVCSルートまたはユーザーが選択したVCSルート)で見つかった場合、TeamCityが必要かどうかを確認する警告が表示されます

  • VCSの設定をTeamCityサーバーの現在のプロジェクト設定で上書きします。または

  • VCSから設定をインポートして、TeamCityサーバーの現在のプロジェクト設定をバージョン管理からの設定に置き換えます。

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

ビルド設定のソースには次の2つがあります。(1)TeamCityサーバーの現在の設定、つまりサーバーに適用された最新の設定の変更です(UIまたはVCSルートの .teamcity ディレクトリへのコミットによって行われます)。)、および(2)ビルド用に選択されたリビジョンのVCSの設定。
したがって、ビルド構成で現在定義されているものとは異なる設定でビルドを開始することが可能です。バージョン対応の設定が有効になっているプロジェクトの場合は、ビルドの開始時に取る設定をTeamCityに指示できます。
これには複数のオプションがあります:

  • TeamCity フィーチャーブランチを使用している場合、バージョン設定に使用されるVCSルートでブランチ仕様を定義できます。TeamCityは、このブランチの設定を使用してブランチでビルドを実行します。

  • .teamcity ディレクトリで行われた変更を使用して個人用ビルドを開始できます。これらの変更はビルドの動作に影響します。

  • 履歴ビルドを実行すると、TeamCityは選択された変更の瞬間に対応する設定を使用しようとします。それ以外の場合、現在のプロジェクト設定が使用されます。

ビルドを開始する前に、TeamCityは、このビルドの構成を .teamcity/settings ディレクトリのビルド内部成果物に保管します。これらの構成ファイルを後で調べて、ビルドで実際に使用された設定を理解できます。

ビルドの開始時に行う設定を定義するには、プロジェクト設定 | バージョン対応設定ページを開き、高度なオプションを表示をクリックして、次のオプションのいずれかを選択します。

  • 常に現在の設定を使用する:すべてのビルドは、TeamCityサーバーからの現在のプロジェクト設定を使用します。ブランチ、履歴、および個人ビルドでの設定の変更は無視されます。ユーザーは、カスタムプロジェクト設定でビルドを実行できません。

  • デフォルトで現在の設定を使用する :ビルドでは、TeamCityサーバーからの最新のプロジェクト設定を使用します。ユーザーは、カスタムビルドダイアログを使用して、古いプロジェクト設定でビルドを実行できます。

  • VCSの設定を使用 :ブランチのビルドおよびVCSの設定を使用する履歴ビルド、ビルド用に計算されたバージョン設定のリビジョンから設定を読み込みます。ユーザーは、IDEから個人用ビルドの構成設定を変更したり、カスタムビルドダイアログを介してTeamCityサーバーで現在のプロジェクト設定でビルドを実行したりできます。
    • 次の設定を変更すると、ビルドに影響します。
      • ビルド番号パターン

      • ビルド・ステップ (ビルドステップのパラメーターとその順序)

      • 構成パラメーターの作成

      • システムプロパティと環境変数

      • エージェントの要件

      • ビルド機能 (自動マージおよびVCSラベリングを除く )

      • 故障状態

      • 成果物公開ルール

      • アーティファクトの依存関係

    • ブランチからの次の設定の変更は無視され、ビルドには影響しません。
      • VCSルートとチェックアウトルール

      • スナップショットの依存関係

      • ビルド・トリガー

      • ビルド構成検出オプション、パーソナルビルドのトリガーの有効化/無効化、ビルド構成タイプなどのビルド構成レベルオプション

      • クリーンアップ規則

安全な設定の保存

VCSの外部にセキュリティデータを保存することをお勧めします。プロジェクト設定 | バージョン対応設定 | 構成ページにはパスワード、APIトークン、その他の安全な設定をVCSの外部に保存するオプションがあります。デフォルトでは、このオプションは、プロジェクトのバージョン管理された設定が初めて有効になった場合に有効になり、すでにVCSに設定を保存しているプロジェクトでは無効になります。

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

トークンの管理

TeamCity UIを介さずに(たとえば、Kotlin DSLを介して)バージョン設定にパスワード(または他の安全な値)を追加する必要がある場合は、このパスワードの代わりに設定で使用されるトークンを生成できます。
プロジェクト設定で、アクションドロップダウンメニューから安全な値のトークンを生成するを選択します。パスワードを入力してトークンの生成をクリックします。生成されたトークンはサーバーに保存されます。パスワードの代わりにそれをコピーして、プロジェクト構成ファイルで使用できます。

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

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

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

Versioned Settings| Tokens

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

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

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

バージョンTeamCity 2017.1より前を使用している場合、VCSにセキュリティ設定を保存することの影響を慎重に検討することをお勧めします。

  • VCSの設定を持つプロジェクトまたはビルド構成にパスワードフィールドが定義されている場合、値はVCSにコミットされた設定に表示されます(ただし、スクランブル形式)。
    • プロジェクト設定がソースコードと同じリポジトリに保存されている場合、リポジトリにアクセスできる人は誰でもこれらのスクランブルされたパスワードを見ることができます。

    • プロジェクト設定がソースコードとは別に専用リポジトリに保存され、 「ビルドの設定変更を表示する」オプションが有効になっている場合、「VCSファイルのコンテンツを表示する」権限を持つすべてのユーザーは、変更差分ビューアーを使用してTeamCity UIのすべての変更を表示できます。

  • VCSを介して任意の方法で設定を変更できるため、TeamCityで構成されたビルド構成のアクセス許可に関係なく、ビルド構成のビルドをトリガーし、ビルド構成の設定を取得できます。

  • 間違った設定や悪意のある設定をコミットすることにより、ユーザーはサーバー全体のパフォーマンスや他のユーザーへのサーバーの表示に影響を与える可能性があります。

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

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

設定形式

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

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

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

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

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

変更の表示

TeamCityは設定を同期するだけでなく、バージョン管理の通常の変更と同じ方法でプロジェクト設定の変更を自動的に表示します。影響を受けるビルド構成に対して表示される変更を構成できます。「プロジェクト設定 | バージョン対応設定 | 構成」タブで「高度なオプションを表示」をクリックし、「ビルドの設定変更を表示する」ボックスをオンにします。

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

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

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

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

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

よくある質問 (FAQ)

Q.別のバージョンのTeamCityサーバーから設定を適用できますか?
A.いいえ。TeamCityデータディレクトリと同様に、設定の形式はTeamCityバージョンごとに異なります。

Q.設定はどこに保存されますか?
A.設定は、VCSルート構成リポジトリパスのルートにある .teamcity ディレクトリに保存されます。GitおよびMercurialの場合、これは常にリポジトリのルートです。VCSルートで設定されているデフォルトのブランチは、GitおよびMercurialで使用されます。専用のVCSルートを作成して、ブランチ(またはPerforce、Subversion、またはAzure DevOps(以前はTFS)の場合はリポジトリパス)を変更できます。

Q. UIで設定を変更した後、ビルドが実行されるまでに遅延が発生するのはなぜですか?
A. UIを介して設定が変更されると、TeamCityは、VCSへのコミットで変更が完了するのを待ってから、最新の変更でビルドを実行します。

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

関連ページ:

Kotlin DSL

XML形式のバージョン管理で設定を保存することに加えて、TeamCityでは(Kotlin言語に基づいて)DSLに設定を保存できます。バージョン管理に保存されたDSLを使用すると、プログラムで設定を定義できます。Kotlinは静的に型指定されるため、IDEで自動補完機能を自動的に受け取ります。これに...

TeamCityデータディレクトリ

TeamCityデータディレクトリは、TeamCityサーバーが構成設定、ビルド結果、および現在の操作ファイルを保存するために使用するファイルシステム上のディレクトリです。ディレクトリはすべての構成設定の主記憶域であり、TeamCityのインストールに不可欠なデータを保持しています。ビルド履歴、ユー...

ビルド構成テンプレート

概要:構成テンプレートを作成するを使用すると、ビルド構成設定の重複を排除できます。いくつかの類似の(必ずしも同一ではない)ビルド構成を持ち、各構成を編集せずに共通の設定を1か所で変更できるようにする場合は、それらの設定でビルド構成テンプレートを作成します。テンプレート設定の変更は、このテンプレートに...

機能ブランチを使用した作業

分散バージョン管理システム(DVCS)のフィーチャーブランチを使用すると、メインの開発とは独立してフィーチャーを操作し、フィーチャーのすべての変更をブランチにコミットして、フィーチャーが完了したときにメインブランチに変更をマージできます。このアプローチは、ソフトウェア開発チームに多くの利点をもたらし...

パーソナルビルド

パーソナルビルドとは、一般的なビルドシーケンスのビルドアウトであり、通常、バージョン管理にまだコミットされていない変更を使用します。通常、パーソナルビルドは、リモート実行プロシージャを介して、サポートされているIDEの 1つから開始されます。以下に説明するように、変更を含むパッチをサーバーに直接アッ...

差分ビューアー

TeamCity差分ビューアーを使用すると、ソース管理で変更されたファイルの2つのバージョン間の違いを確認し、これらの違いをナビゲートできます。ビューアーには、TeamCity UIの変更リストが表示されるほぼすべての場所(プロジェクトページ、ビルド構成ホームページ、ビルド結果ページの変更タブなど)...