TeamCity On-Premises 2026.2 Help

チェーンでデータを渡す

ビルドチェーンのメンバーは、二種類のデータを交換できます：

  • ファイル — アーティファクトの依存関係を通じて。 アップストリームビルドはファイルを公開し、ダウンストリームビルドは開始前にそれらをダウンロードします。

  • 値 — 出力パラメーターを通じて。 あるオブジェクトで設定された名前と値のペアは、チェーンのさらに下流にある別のオブジェクトによって読み取られます。

どちらの仕組みもチェーンの方向に従って流れます: データはアップストリームからダウンストリームへ移動し、その逆には移動しません。

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

アーティファクトの依存関係は、あるビルドの出力(アーティファクト )を別のビルドで再利用します。 設定すると、TeamCity はダウンストリームビルドが開始する前に、必要なファイルをエージェントにダウンロードします。

アーティファクトは以下から取得できます：

  • 同じチェーン内のアップストリームオブジェクトのビルド。

  • チェーンに含まれていない構成のビルド。

  • 同じ構成の以前のビルド。

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

ビルド構成では、構成設定の 依存関係 ページでアーティファクトの依存関係を追加します。

アーティファクト依存関係を追加する

ダイアログには、以下の主要な設定があります：

アーティファクトの依存関係ダイアログ
依存先

使用するアーティファクトを持つ構成。

からアーティファクトを入手する

アーティファクトを取得するソース構成のビルド：

  • 最新の成功したビルド/最新の固定ビルド/最新の完了したビルド — 一致する最新のビルド。

  • 同じチェーンからビルドする — 同じチェーンのビルド。 スナップショット依存関係と一緒に使用します。 ソースがチェーンの外部にある場合、ビルドは失敗します。

  • 同じチェーンのビルドまたは最後に完了したビルド — 上記と同じですが、ソースがチェーン内にない場合は、完了済みの最新ビルドにフォールバックします。

  • 指定されたビルド番号のビルド/指定されたタグの最新の完了したビルド — 番号またはタグで識別される特定のビルド。

アーティファクトルール

ダウンロードするファイルと配置先。 以下の アーティファクトルールを参照してください。

アーティファクトをダウンロードする前に宛先パスをクリーンアップする

ダウンロード前に宛先ディレクトリの内容を削除し、すべての包含ルールに適用されます。

パイプラインでは、アーティファクトの依存関係は YAML で構成されます。 これには二つの別々のパイプラインが関係し、それぞれに独自の構成ファイルがあります。

まず、 上流 パイプライン内のジョブが、 files-publication ブロックを介してファイルを公開します：

# Upstream pipeline jobs: Build: steps: - type: gradle tasks: clean build files-publication: - path: ./build/libs/todo.jar share-with-jobs: true publish-artifact: true

次に、 ダウンストリーム パイプライン内のジョブが、 download-artifacts ブロックを介してインポートし、自身の dependencies で宣言されたアップストリームパイプラインを参照します：

# Downstream pipeline jobs: Docker: steps: - type: script script-content: docker build -t myapp:%build.number% . download-artifacts: - UpstreamPipeline_ID: # same ID as in the 'dependencies' block from: dependency artifact-rules: todo.jar=>./build/libs clean-destination: true dependencies: - UpstreamPipeline_ID: reuse: none

アーティファクトルール

アーティファクトルールは、ダウンロードするアーティファクトとその保存先を指定します。 各ルールは個別の行に記述し、次の構文を使用します：

[+:|-:|?:]SourcePath[!ArchivePath][=>DestinationPath]
プレフィックス

  • +： — 含める(デフォルト。 マイライブラリ.dll と +:マイライブラリ.dll は同じです)。

  • -： — ファイルまたはパターンをダウンロードから除外します。

  • ？： — オプションのインクルード。 ファイルが見つからない場合、ビルドは失敗せず、警告付きで続行されます。

ソースパス

ソースビルドのアーティファクトディレクトリからの相対パス。 ファイル、ディレクトリ、または Ant 風ワイルドカードを指定できます。 ソースディレクトリ構造は、最初のワイルドカードから保持されます。

アーカイブパス

ダウンロードしたアーカイブ(ZIP、 7z、 JAR、 TAR、 TAR.GZ など)からファイルを抽出します。 たとえば、 リリース.zip!*.DLL はアーカイブルートから .DLL ファイルを抽出します。

宛先パス

エージェント上のターゲットディレクトリ。ビルドチェックアウトディレクトリからの相対パスです。 省略した場合、アーティファクトはチェックアウトルートに配置されます。 -： ルールでは無視されます。

例:

# Download a directory tree into lib/ (a/b/c/file.txt → lib/c/file.txt) a/b/**=>lib # Download all text files, preserving structure **/*.txt=>lib # Extract all DLLs from matching archives release-*.zip!*.dll=>dlls # Download everything except one file **/*.txt=>texts -:bad/exclude.txt # Optional file — build continues even if it is missing ?:output.txt

？： プレフィックスは、 部分チェーンで特に便利です: 通常はファイルを提供するアップストリームビルドがスキップされた場合でも、オプションのルールによりダウンストリームビルドの失敗を防げます。

パラメーター

チェーンメンバーは ビルドパラメーターを通じて値を交換します。 このセクションは簡単な概要です - 完全な構文、例、エッジケースについては、 ビルドチェーンでパラメーターを使用する を参照してください。

値は、アップストリームオブジェクトで 出力パラメーター として宣言することで、チェーンの下流に共有されます。 入力パラメーターは所有者のみに限定され、出力パラメーターはダウンストリームオブジェクトから参照できます。

アップストリーム値を読み取る

ダウンストリームオブジェクトは、 dep.<upstream-ID>.<param-name> を介してアップストリームの出力パラメーターを読み取ります。

別のジョブの値を読み取る

単一のパイプライン内で、ジョブは job.<job-ID>.<param-name> を介して先行ジョブのパラメーターを読み取ります。

アップストリーム値をオーバーライドする

ダウンストリームオブジェクトは、 override.dep.<upstream-ID>.<param-name> を介してアップストリームの入力パラメーターに書き戻します。 これは、データがチェーンの方向に逆らって流れる唯一のケースであり、アップストリームビルドが開始する前に解決されます。

出力パラメーターは、宣言したオブジェクトではなく、 他のオブジェクトによって読み取られるように設計されています。 構成またはパイプラインが自身の出力パラメーターを参照すると、その参照は解決されません: TeamCity は未解決の %...% を 暗黙のエージェント要件として扱い、ビルドは "no compatible agents" エラーで開始に失敗します。 以下のスニペットでこれを示します。

parameters: PipelineInputParam: foo output-parameters: PipelineOutputParam: bar jobs: Job1: name: Job 1 steps: - type: script script-content: |- # Prints 'foo' echo "Input param: %PipelineInputParam%" # Unresolved reference: no compatible agents echo "Output param: %PipelineOutputParam%"

ビルド構成では、同等の宣言に パラメーター ブロックと outputParams ブロックを使用します。 ビルドチェーンでパラメーターを使用する で、上記の三つのパターンすべての完全な例、複数のオブジェクトを一度にオーバーライドするための * ワイルドカード、競合する場合の解決ルールを参照してください。

高度な概念

ビルドレベルの認証

システムプロパティ system.teamcity.auth.userId と system.teamcity.auth.password は、TeamCity サーバーでの認証に使用できる、自動生成されたビルド固有の値を格納します。 値はビルドが実行されている間だけ有効です。 この生成されたユーザーは、ビルド関連の操作を許可する権限が制限されています。 このユーザーの主な目的は、認証を使用してビルドスクリプト内で他の TeamCity ビルドからアーティファクトをダウンロードすることです。

プロパティを使用すると、サーバーがビルドによってダウンロードされたアーティファクトを追跡できるため、実際のユーザー資格情報を使用するよりも望ましい方法です。 アーティファクトがビルド構成アーティファクトの依存関係によって、または提供されたプロパティを使用してダウンロードされた場合、ビルドで使用される特定のアーティファクトは、 ビルド結果 ページの 依存関係 タブに表示されます。 さらに、アーティファクトを取得するために使用されたビルドは、異なる clean-up ロジックを持つように構成できます。

Ant ビルドスクリプトを使用したアーティファクトの依存関係の構成

このセクションでは、ビルドスクリプト内で TeamCity ビルドアーティファクトをダウンロードする方法について説明します。 これらの手順は、TeamCity の外部からアーティファクトをダウンロードする場合にも使用できます。

ビルド間のアーティファクト依存関係を処理するには、このソリューションは TeamCity UI で依存関係を構成するより複雑ですが、より高い柔軟性があります。 例: この方法で依存関係を管理すると、個人用ビルドを開始して、ビルドが依存関係と互換性があることを確認できます。

Ant ビルドスクリプトで依存関係を設定するには

  1. Ivy をダウンロードします。

  2. ビルドのクラスパスに Ivy を追加します。

  3. TeamCity リポジトリに関するメタ情報を含む Ivy 設定.xml ファイルを作成します。 このファイルの内容は次のとおりです。

    <ivysettings> <property name='ivy.checksums' value=''/> <caches defaultCache="${teamcity.build.tempDir}/.ivy/cache"/> <statuses> <status name='integration' integration='true'/> </statuses> <resolvers> <url name='teamcity-rep' alwaysCheckExactRevision='yes' checkmodified='true'> <ivy pattern='http://YOUR_TEAMCITY_HOST_NAME/httpAuth/repository/download/[module]/[revision]/teamcity-ivy.xml' /> <artifact pattern='http://YOUR_TEAMCITY_HOST_NAME/httpAuth/repository/download/[module]/[revision]/[artifact](.[ext])' /> </url> </resolvers> <modules> <module organisation='.*' name='.*' matcher='regexp' resolver='teamcity-rep' /> </modules> </ivysettings>

  4. 対象 TeamCity ホスト名 を TeamCity サーバーのホスト名に置き換えます。

  5. ビルド.xml が実行されるディレクトリに Ivy 設定.xml を配置します。

  6. 同じディレクトリに、ダウンロードするアーティファクトと配置先を定義する Ivy.xml ファイルを作成します。例：

    <ivy-module version="1.3"> <info organisation="YOUR_ORGANIZATION" module="YOUR_MODULE"/> <dependencies> <dependency org="org" name="BUILD_TYPE_EXT_ID" rev="BUILD_REVISION"> <include name="ARTIFACT_FILE_NAME_WITHOUT_EXTENSION" ext="ARTIFACT_FILE_NAME_EXTENSION" matcher="exactOrRegexp"/> </dependency> </dependencies> </ivy-module>

    where:

    • 対象組織 はあなたの組織の名前に置き換えてください。

    • 対象モジュール は、アーティファクトが使用されるプロジェクトまたはモジュールの名前に置き換えます。

    • ビルドタイプ外部 ID は、アーティファクトがダウンロードされるビルド構成の 外部 ID に置き換えられます。

    • ビルドリビジョン はビルド番号または以下の文字列のいずれかです: * 最新.最後に完了

      • 最新.最後に成功

      • 最新.最後にピン留め済み

    • タグ名.tcbuildtag - TAG_NAME タグでタグ付けされた最後のビルド

    • アーティファクトファイル名_拡張子なし ファイル名または拡張部分なしのアーティファクトの正規表現。

    • アーティファクトファイル名拡張子 アーティファクトファイル名の拡張子部分。

  7. ビルド.xml ファイルを変更し、アーティファクトをダウンロードするためのタスクを追加します。例 (Ant 1.6 以降に適用可能)：

    <target name="fetchArtifacts" description="Retrieves artifacts for TeamCity" xmlns:ivy="antlib:org.apache.ivy.ant"> <taskdef uri="antlib:org.apache.ivy.ant" resource="org/apache/ivy/ant/antlib.xml"/> <classpath> <pathelement location="${basedir}/lib/ivy-2.0.jar"/> <pathelement location="${basedir}/lib/commons-httpclient-3.0.1.jar"/> <pathelement location="${basedir}/lib/commons-logging.jar"/> <pathelement location="${basedir}/lib/commons-codec-1.3.jar"/> </classpath> </taskdef> <ivy:configure file="${basedir}/ivyconf.xml" /> <ivy:cleancache /> <ivy:retrieve pattern="${basedir}/[artifact].[ext]"/> </target>

アーティファクトリポジトリは、基本認証によって保護されています。 アーティファクトにアクセスするには、<ivy:configure/> タスクに資格情報を指定する必要があります。 例:

<ivy:configure file="${basedir}/ivyconf.xml" host="TEAMCITY_HOST" realm="TeamCity" username="USER_ID" passwd="PASSWORD"/>

ここで TEAMCITY ホスト は TeamCity サーバーのホスト名または IP アドレスです (ポートとサーブレットコンテキストは含みません)。
USER_ID/PASSWORD には、通常の TeamCity ユーザーのユーザー名/パスワード (そのユーザーには、ソースビルド構成のアーティファクトにアクセスするための対応する権限が必要です) またはシステムプロパティ system.teamcity.auth.userId/system.teamcity.auth.password のいずれかを使用できます。

2026 年 9 月 11 日
チェーン依存関係の構成ビルドチェーンを実行