一般設定を構成する

一般的なビルド構成設定

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

設定	説明
名前	ビルド構成名。
ビルド構成 ID	システム内のすべてのビルド構成とテンプレートにわたる構成の一意の ID は、ビルド構成名から自動的に生成されますが、手動で設定することもできます。ビルド構成にグローバルに一意の ID を指定し、その前にプロジェクト ID を付けるようにしてください。ビルド構成が作成された後、その ID を変更できます。また、ID を使用して、Web UI へのブックマークされたリンクと REST API への呼び出しに対応する変更を加えることを強くお勧めします。
説明	ビルド構成のオプションの説明。
ビルド番号の形式	ビルド開始時に解決され、ビルド番号に割り当てられるパターン。
ビルドカウンター	ビルド番号付けに使用されるカウンターを指定してください。各ビルドはビルドカウンターを 1 増加させます。リセットリンクを使用してカウンター値を 1 に戻します。
アーティファクトを公開する	アーティファクトをいつ公開するかを選択します。 " ビルドが失敗しても "（デフォルト）: 前のステップがすべて完了したかどうかにかかわらず、ビルドの最後のステップでアーティファクトを公開します。 " ビルドステータスが成功した場合のみ ": 前のステップがすべて正常に完了した場合は、ビルドの最後のステップでアーティファクトを公開します。TeamCity は、アーティファクトを公開する前に、サーバー上の現在のビルド状況を確認します。 "build stop コマンドが発行された場合でも常に ": 中断されたものであっても（すべてのビルドについてアーティファクトを公開します（たとえば、`stop` コマンドが発行された後、ビルド失敗条件で指定されたタイムアウト後）。この設定は、ビルドスクリプトで構成されたアーティファクトの公開には影響しません。アーティファクトの公開中に `stop` コマンドが発行されると、選択したオプションに関係なく、公開操作は停止されます。
アーティファクトパス	ビルドのアーティファクトを定義するパターン。最初のビルドが実行された後、エージェントのチェックアウトディレクトリを参照してアーティファクトのパスを構成できます。
ビルドオプション	このビルド構成のビルドに追加オプションを指定してください。ハングしているビルドの検出個人用ビルドの開始を許可ステータスウィジェットを有効にする HTML ステータスウィジェット同時実行ビルド数の制限

ビルド番号の形式

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

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

パターン	説明
`%build.counter%`	各ビルド構成に固有のビルドカウンター。TeamCity によって維持され、新しいビルドの開始ごとに次の整数値に解決されます。カウンターの現在の値は、ビルドカウンターフィールドで編集できます。
`%build.vcs.number.<VCS_root_name>%`	`<VCS_root_name>` 名の VCS ルートのビルドに使用されるリビジョン。プロパティの続きを読む。
`%property.name%`	対応する名前のビルドプロパティの値。すべての定義済みのビルドパラメーターがサポートされています（参照専用サーバーのプロパティを含む）。

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

アーティファクトパス

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

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

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

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

directory1 を除くすべてのファイルを target_directory に公開するよう TeamCity に指示します。

行フォーマットの説明

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

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

file_name — ファイルを公開します。名前は、ビルドチェックアウトディレクトリに関連している必要があります。
directory_name — 指定されたディレクトリ内のすべてのファイルとサブディレクトリを公開します。ディレクトリ名は、ビルドチェックアウトディレクトリからの相対パスである必要があります。ファイルは、指定されたディレクトリのディレクトリ構造を保持して公開されます（ディレクトリ自体は含まれません）。
wildcard — アリのようなワイルドカードパターンに一致するファイルを公開します (* および ** ワイルドカードのみがサポートされています)。ワイルドカードは、ビルドチェックアウトディレクトリへの相対パスを表す必要があります。ファイルは、ワイルドカードに一致するディレクトリの構造を保持して公開されます (「静的」テキストに一致するディレクトリは作成されません)。つまり、TeamCity は、パターン内のワイルドカードの最初の出現からディレクトリを作成します。
アーティファクトの仕様でビルドパラメーターを使用できます。例: mylib-%system.build.number%.zip を使用して、名前にビルド番号が含まれるファイルを参照します。

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

target_directory — （オプション）パターンの左側で決定されたファイルを含む、結果のビルドのアーティファクト内のディレクトリ。
target_archive — （オプション）パターンの左側で決定されたビルドアーティファクトをパックすることによって TeamCity によって作成されるアーカイブへのパス。TeamCity は、サポートされているアーカイブ拡張子、つまり .zip、.7z、.jar、.tar.gz または .tgz で終わる場合は常に、パターンの右側の部分を target_archive として扱います。

シンボリックリンクの公開

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

公開されたアーカイブには、シンボリックリンクがシンボリックリンクとして含まれています。これはデフォルトの動作です。アーティファクトパスを teamcity:symbolicLinks 属性で明示的に装飾して、この動作を強制できます。
#teamcity:symbolicLinks=as-is %teamcity.build.checkoutDir%/build=>build.zip
公開されたアーカイブには、シンボリックリンクによって参照されるファイルとフォルダーが含まれます。この動作を有効にするには、次のようにアーティファクトルールを teamcity:symbolicLinks 属性で修飾します。
#teamcity:symbolicLinks=inline %teamcity.build.checkoutDir%/build=>build.zip

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

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

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

install.zip — ビルドアーティファクトで install.zip という名前のファイルを公開します。
dist — dist ディレクトリのコンテンツを公開します。
target/*.jar — ターゲットディレクトリにあるすべての jar ファイルを公開します。
target/**/*.txt=> docs — ターゲットディレクトリとそのサブディレクトリにあるすべての txt ファイルを公開します。これらのファイルは、docs ディレクトリのビルドアーティファクトで利用できます。
reports => reports, distrib/idea*.zip — レポートディレクトリを、idea*.zip に一致するレポートおよびファイルとして distrib ディレクトリからアーティファクトルートに公開します。
必要に応じて、zip アーカイブ内の相対パス results\result1\Dir1\Dir2 => archive.zip!results/result1/Dir1 を使用できます。
同じ target_archive 名を複数回使用できます。例:
- +:*/*.html => report.zip
- +:*/*.css => report.zip!/css/
- -:*/*.txt => report.zip

ビルドオプション

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

ハングしているビルドの検出

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

個人用ビルドの開始を許可

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

このオプションを使用すると、ユーザー認証を必要とせずに、ビルド構成内の最後のビルドのステータスと基本的な詳細を取得できます。これにより、ビルド構成内の特定のビルドのステータスを取得することもできます（ただし、ビルドを一覧表示することはできず、ビルドステータス（success/failure/internal error/cancelled）以外の情報は利用できません）。

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

この機能を使用すると、会社の Web サイト、Wiki、Confluence、その他の Web ページで現在のプロジェクトステータスの概要を把握できます。
ステータスウィジェットを有効にするオプションを有効にすると、HTML スニペットを外部 Web ページに含めることができ、現在のビルド構成ステータスが表示されます。
ビルドステータスアイコンを単一のイメージとして表示するには、REST ビルド状況アイコンをチェックしてください。

以下のビルドプロセス情報がステータスウィジェットによって提供されます。

最新のビルド結果
ビルド番号
ビルド状況
最新のビルドアーティファクトへのリンク。ステータスウィジェットは、ユーザーが TeamCity にログインすることを要求しません。

この機能が有効になっているときは、Web ページのソースに次のコードを含める必要があります。

このコードサンプルを <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 を使用します。
<iframe src="<TeamCity_server_URL>/externalStatus.html"/>
<head> セクションを変更せずにデフォルトの CSS スタイルを含める場合は、withCss=true パラメーターを追加します。
特定のビルド構成に関する最新のステータス情報を提供するには、URL で次のパラメーターを必要な回数だけ使用します。
&buildTypeId=<external build configuration ID>

&[buildTypeId](identifier.md)=<external build configuration ID> を &[projectId](identifier.md)=<external project ID> に置き換えることで、すべてのプロジェクトビルド構成のステータスを表示することもできます。これらのパラメーターの組み合わせを選択して、必要なプロジェクトを表示したり、Web ページに構成を構築したりできます。

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

同時実行ビルド数の制限

すべてのエージェントで同時に実行できるビルドの数を制限できます。このオプションは、ビルドへのリソースの割り当てを改善し、すべてのエージェントが単一のプロジェクトのビルドでビジー状態になる状況を回避できます。

関連フィールドを使用して、ビルド構成のビルドの総数を制限し、ブランチごとに詳細な制限を構成できます。

ビルド構成の場合は、ビルドの合計最大数を入力します。この数はデフォルトで 0 に設定されており、無制限の数のビルドを同時に実行できます。
ブランチごとのビルド制限については、改行で区切られたルールのリストを入力します。各ルールは branch:number パターンに従う必要があります。ここで、branch は論理ブランチ名または * を含むパターンのいずれかであり、number はパターンに一致する各ブランチで同時に実行できるビルドの最大数を指定します。0 は、指定されたブランチで無制限の数のビルドを許可します。

2025 年 5 月 19 日