TeamCity On-Premises 2026.2 Help

一般設定の構成

一般ビルド構成設定

ビルド構成を作成するときは、次の設定を指定してください。

名前

ビルド構成名。

ビルド構成 ID

システム内のすべてのビルド構成とテンプレートで構成を一意に識別する ID です。ビルド構成のお名前から自動生成されますが、手動で設定することもできます。
ビルド構成にはグローバルに一意の ID を指定し、その先頭にプロジェクト ID を付けてください。
ビルド構成の作成後でも ID は変更できます。ID を使用しているウェブ UI へのブックマークリンクと REST API 呼び出しにも、対応する変更を加えることを強くおすすめします。

説明

ビルド構成のオプションの説明。

ビルド番号のフォーマット

ビルド開始時に解決され、 ビルド番号に割り当てられるパターン。

ビルドカウンター

ビルド番号付けに使用されるカウンターを指定してください。 各ビルドはビルドカウンターを 1 増加させます。 リセットリンクを使用してカウンター値を 1 に戻します。

アーティファクトを公開

アーティファクトをいつ公開するかを選択します。

  • " ビルドが失敗しても"（デフォルト）: 前のステップがすべて完了したかどうかにかかわらず、ビルドの最後のステップでアーティファクトを公開します。

  • " ビルドステータスが成功した場合のみ": 前のステップがすべて正常に完了した場合は、ビルドの最後のステップでアーティファクトを公開します。 TeamCity はアーティファクトを公開する前に、サーバー上の現在のビルドステータスを確認します。

  • " build stop コマンドが発行された場合でも常に ": 中断されたものであっても（すべてのビルドについてアーティファクトを公開します（たとえば、 停止 コマンドが発行された後、ビルド失敗条件で指定されたタイムアウト後）。

この設定は、 ビルドスクリプトで構成されたアーティファクトの公開には影響しません。

アーティファクトパス

ビルドのアーティファクトを定義するパターン。 最初のビルドが実行された後、エージェントの チェックアウトディレクトリを参照してアーティファクトのパスを構成できます。

詳細については、 アーティファクトパス を参照してください。

ビルドオプション

個々のビルドに関連する追加 オプション:

ビルド番号の形式

ビルド番号の形式フィールドでは、ビルド開始時に解決され、 ビルド番号に割り当てられるパターンを指定できます。

このパターンでは、以下の置換がサポートされています。

%build.counter%

各ビルド構成に固有のビルドカウンター。 TeamCity によって管理され、新しいビルドが開始されるたびに次の整数値に解決されます。 カウンターの現在の値は、 ビルドカウンターフィールドで編集できます。

%build.vcs.number.<VCS_root_name>%

<VCS_ルート_お名前> 名の VCS ルートのビルドに使用されるリビジョン。 プロパティの 続きを読む。

%property.name%

対応する名前のビルドプロパティの値。 すべての 定義済みのビルドパラメーターがサポートされています（参照専用サーバーのプロパティを含む）。

必須ではありませんが、ビルド番号が一意であることを確認することを強くお勧めします。 ビルド番号にビルドカウンターを含め、ビルドカウンターを小さい値にリセットしないでください。 ビルドスクリプト内からビルド番号を変更することもできます。 詳細については、 TeamCity とビルドスクリプトの連携を参照してください。

アーティファクトパス

ビルドアーティファクトは、ビルドによって生成されるファイルです。TeamCity サーバーに保存され、TeamCity UI からダウンロードしたり、他のビルドでアーティファクト依存関係として使用したりできます。 ビルド構成の 一般設定 ページで、ビルド後にサーバーにアップロードされるエージェント上のファイルのパターンを指定できます。

エージェントのビルドが完了したら、チェックアウトディレクトリブラウザー chechoutdirBrowser.png （エージェント上のチェックアウトディレクトリの内容を一覧表示）を使用して、ツリーからアーティファクトを選択できます。 TeamCity はそれらへのパスを入力フィールドに配置します。

アーティファクトパスフィールドは、相対（ビルドチェックアウトディレクトリへの）パスと絶対パスをサポートします。 相対パスを使用することをお勧めします。 正確なファイルパスまたはパターンを 1 行に 1 つずつ指定するか、コンマ区切りで指定できます。 パターンは、 * および ** ワイルドカードをサポートします（以下を参照）。 各行は、ビルドするアーティファクトとして公開するファイルまたはディレクトリを含める [+:]ソース [=> ターゲット] および除外する -:ソース [=> ターゲット] の形式にすることができます。 角括弧で囲まれた部品はオプションです。 ルールは適切な部分ごとにグループ化され、出現順に適用されます。

+:**/* => target_directory -:directory1 => target_directory

ディレクトリ 1 を除くすべてのファイルを ターゲット_ディレクトリ に公開するよう TeamCity に指示します。

行フォーマットの説明

file_name|directory_name|wildcard [ => target_directory|target_archive ]

ソース部分では絶対パスがサポートされていますが、 ビルドチェックアウトディレクトリからの相対パスを使用することをおすすめします。

  • ファイル_お名前 — ファイルを公開します。 名前は、ビルドチェックアウトディレクトリに関連している必要があります。

  • ディレクトリ_お名前 — 指定されたディレクトリ内のすべてのファイルとサブディレクトリを公開します。 ディレクトリ名は、ビルドチェックアウトディレクトリからの相対パスである必要があります。 ファイルは、指定されたディレクトリのディレクトリ構造を保持して公開されます（ディレクトリ自体は含まれません）。

  • ワイルドカード — アリのようなワイルドカードパターンに一致するファイルを公開します (* および ** ワイルドカードのみがサポートされています)。 ワイルドカードは、ビルドチェックアウトディレクトリへの相対パスを表す必要があります。 ファイルは、ワイルドカードに一致するディレクトリの構造を保持して公開されます (「静的」テキストに一致するディレクトリは作成されません)。 つまり、TeamCity はパターン内でワイルドカードが最初に出現する位置からディレクトリを作成します。

  • アーティファクトの仕様で ビルドパラメーターを使用できます。 例: mylib-%system.build.number%.zip を使用して、名前にビルド番号が含まれるファイルを参照します。

=> シンボルで始まり、その後にターゲットディレクトリのお名前が続く省略可能な部分を使用すると、ファイルを指定したターゲットディレクトリに公開できます。 ターゲットディレクトリを省略すると、ファイルはビルドアーティファクトのルートに公開されます。 。 (ドット) をビルドチェックアウトディレクトリへの参照として使用できます。
ターゲットパスを絶対パスにすることはできません。 相対パスではないパスは、ビルド中にエラーになります。

  • ターゲット_ディレクトリ — （オプション）パターンの左側で決定されたファイルを含む、結果のビルドのアーティファクト内のディレクトリ。

  • ターゲット_アーカイブ — (オプション) パターンの左側で決定されたビルドアーティファクトをパックして TeamCity が作成するアーカイブへのパス。 TeamCity は、パターンの右側の部分を ターゲット_アーカイブ として扱います。これは、末尾が サポートされているアーカイブ拡張機能 、つまり .zip、 .7z、 .jar、 .tar.gz、 .tgz、 tar.zst 、または .tzst のいずれかである場合です。

シンボリックリンク (シンボリックリンクまたはソフトリンク) は、他のファイルまたはディレクトリを指し、それらの絶対パスまたは相対パスを表す Linux ファイルです。 ビルドアーティファクトとして公開する必要があるディレクトリにシンボリックリンクが含まれている場合は、次の 2 つのモードのいずれかを選択できます。

  • 公開されたアーカイブには、シンボリックリンクがシンボリックリンクとして含まれています。 これはデフォルトの動作です。 アーティファクトパスを teamcity:シンボリックリンク 属性で明示的に装飾して、この動作を強制できます。

    #teamcity:symbolicLinks=as-is %teamcity.build.checkoutDir%/build=>build.zip

  • 公開されたアーカイブには、シンボリックリンクによって参照されるファイルとフォルダーが含まれます。 この動作を有効にするには、次のようにアーティファクトルールを teamcity:シンボリックリンク 属性で修飾します。

    #teamcity:symbolicLinks=inline %teamcity.build.checkoutDir%/build=>build.zip

属性は、その直下で宣言されたアーティファクト公開ルールのみに影響することに注意してください。 例: 以下のサンプルでは、 Archive_A のみにシンボリックリンクによって参照されるファイルとフォルダーが含まれます。 Archive_B はデフォルトの動作を採用し、シンボリックリンクをファイルとして組み込みます。

#teamcity:symbolicLinks=inline Dir_A=>Archive_A.zip Dir_B=>Archive_B.zip

アーティファクトパスの例

  • install.zip — ビルドアーティファクトで install.zip という名前のファイルを公開します。

  • 配布 — dist ディレクトリのコンテンツを公開します。

  • ターゲット/*.jar — ターゲットディレクトリにあるすべての JAR ファイルを公開します。

  • ターゲット/**/*.txt=> docs — ターゲットディレクトリとそのサブディレクトリにあるすべての txt ファイルを公開します。 これらのファイルは、 ドキュメント ディレクトリのビルドアーティファクトで利用できます。

  • reports => reports、distrib/idea*.zip — レポートディレクトリを、 idea*.zip に一致するレポートおよびファイルとして 配布 ディレクトリからアーティファクトルートに公開します。

  • 必要に応じて、zip アーカイブ内の相対パス results\result1\Dir1\Dir2 => archive.zip!results/result1/Dir1 を使用できます。

  • 同じ ターゲット_アーカイブ お名前を複数回使用できます。例：

    • +:*/*.html => report.zip

    • +:*/*.css => report.zip!/css/

    • -:*/*.txt => report.zip

ビルドオプション

以下のオプションは構成を構築するために利用可能です:

ハングしたビルドの検出

おそらく「ハングしている」ビルドを検出するには、 ハングしているビルドの検出を使用可能にするオプションを選択します。 ビルドの実行時間が推定 平均実行時間 を大幅に超過し、推定値を超えてからビルドがメッセージを送信していない場合、ビルドは「ハングしている」とみなされます。 ハングしたビルドを適切に検出するには、TeamCity は複数のビルドに基づいてビルドの平均実行時間を推定する必要があります。 そのため、新しいビルド構成がある場合は、数回のビルドが実行された後にこの機能を有効化すると、TeamCity が平均実行時間を予測するのに十分な情報を得られます。

個人用ビルドのトリガーを許可

個人用ビルドのトリガーを許可する オプションのチェックを外すと (デフォルトではオン)、 個人用ビルドの実行を制限できます。

ステータスウィジェットを有効化

このオプションを有効化すると、ユーザー認証を必要とせずに、ビルド構成の最後のビルドのステータスと基本情報を取得できます。 これにより、ビルド構成内の特定のビルドのステータスも取得できます (ただし、ビルドを一覧表示することはできず、ビルドステータス (成功/失敗/内部エラー/キャンセル済み) 以外の情報は利用できません)。

ステータスは、 以下で説明する HTML ステータスウィジェット経由、または単一のアイコン経由で取得できます: REST API を使用するか、 アクション メニューから ビルド構成ホーム で取得できます。ビーコンのステータスは、HTML ステータスウィジェット経由、または単一のアイコン経由で取得できます。単一のアイコンは、REST API を使用するか、メニューから取得できます。

HTML ステータスウィジェット

この機能を使用すると、会社のウェブサイト、wiki、Confluence、またはその他のウェブページで、現在のプロジェクトステータスの概要を確認できます。
ステータスウィジェットを有効化 オプションが有効化されている場合、HTML スニペットを外部ウェブページに含めることができ、現在のビルド構成ステータスが表示されます。
単一の画像としてのビルドステータスアイコンについては、 REST ビルドステータスアイコンを確認してください。

ステータスウィジェットから、次のビルドプロセス情報が提供されます：

  • 最新のビルド結果

  • ビルド番号

  • ビルドステータス

  • 最新のビルドアーティファクトへのリンク。 ステータスウィジェットでは、ユーザーが TeamCity にログインする必要はありません。

機能が有効化されている場合は、ウェブページのソースに次のコードスニペットを含める必要があります：

  • このコードサンプルを <head> セクションに追加します (または、代わりに withCss=true パラメーターを externalStatus.html に追加します)：

    <style type="text/css"> @import "<TeamCity_server_URL>/css/status/externalStatus.css"; </style>

  • ビルド構成のステータスを表示する場所に、このコードサンプルを挿入します：

    <script type="text/javascript" src="<TeamCity_server_URL>/externalStatus.html?js=1"> </script>

  • JavaScript の代わりにプレーン HTML を使用する場合は、 js=1 パラメーターを省略し、スクリプトの代わりに インラインフレーム を使用します：

    <iframe src="<TeamCity_server_URL>/externalStatus.html"/>

  • デフォルトの CSS スタイルを <head> セクションを変更せずに含める場合は、 withCss=true パラメーターを追加します。
    特定のビルド構成に関するアップデートされたステータス情報を提供するには、URL で必要な回数だけ次のパラメーターを使用します：

    &buildTypeId=<external build configuration ID>

&[buildTypeId](identifier.md)=<外部ビルド構成識別子> を &[projectId](identifier.md)=<外部プロジェクト識別子> に置き換えることで、すべてのプロジェクトのビルド構成のステータスを表示することもできます。 必要なプロジェクトとビルド構成をウェブページに表示するために、これらのパラメーターの組み合わせを選択できます。

外部ステータス.css ファイルをダウンロードしてカスタマイズすることもできます (たとえば、 display: none を使用して一部の列を無効化できます。 外部ステータス.css 内のコメントを参照してください)。 ただし、この場合は、 含めないwithCss=true パラメーターではなく、代わりに CSS スタイルを明示的に、できれば <head> セクションで指定する必要があります。

同時実行ビルド数の制限

このビルド構成の最大同時ビルド数 設定は、この構成のビルドを同時に実行できる数を定義します。 これにより、単一の構成が利用可能なエージェントをすべて占有してしまうのを防ぐことができます。 以下のいずれかを指定できます。

  • 数値。 0 は無制限を意味します

  • 改行で区切られた ブランチ:number ルールを使用して、異なるブランチに対して異なる制限を設定します。

ブランチ の値は、 論理的なブランチ名 、またはアスタリスク (*) をワイルドカードとして使用するパターンのいずれかになります。

<default>:0 # no limit for the builds running on default branch pull/*:1 # no more than one build for each pull request

上限に達した場合 オプションは、同時実行ビルドの最大数がすでに実行されている場合の動作を制御します。 TeamCity は、実行中のビルドが完了するまで新しいビルドをキューに保持するか、最も古い実行中のビルドをキャンセルして新しいビルド用の空きスペースを確保できます。

2026 年 9 月 11 日
ビルド構成の作成と編集。ビルド構成タイプの変更