ビルドチェーンでパラメーターを使用する

このトピックでは、TeamCity のビルドパラメーターを使用して、ビルドチェーンの構成とパイプライン間、および単一パイプラインの個別ジョブ間で簡単なデータを交換する方法を説明します。

入力パラメーターと出力パラメーター

ビルド構成とパイプラインでは、入力と出力という 2 種類のパラメーターを作成できます。

どちらも手動で作成された名前と値のペアです。主な違いは、想定される使用例とアクセシビリティ設定にあります。

入力パラメーター

入力パラメーターは、それを定義する同じ構成/パイプラインで使用されるように設計されています。たとえば、デフォルトのブランチ名を保存し、 VCS ルート設定で参照される入力パラメーターです。この値は他の構成では使用されないため、他の構成から見えるようにするべきではありません。

出力パラメーター

出力パラメーターは、あるビルド構成/パイプラインで構成されますが、別のビルド構成/パイプラインからスナップショットまたはアーティファクト依存関係を介してアクセスできます。たとえば、Docker イメージをビルドするビルド構成は、このイメージ名をそのパラメーターに書き込むことができます。そのパラメーターは後で、このイメージをレジストリにデプロイするダウンストリーム構成で使用されます。

出力パラメーターは、既存のパラメーターをそのまま共有したり、変更されたパラメーターや定数を共有したりできます。

outputParams {
    // Expose predefined parameter as is
    param("originConfName", "%system.teamcity.buildConfName%")
    
    // Expose modified parameter value
    param("buildNumber", "Build %system.build.number%")
    
    // Expose input parameter as is
    param("name", "%customInputParam%")
    
    // Expose static value
    param("number", "54")
}

    

アップストリームオブジェクトのパラメーターを読み取る

ジョブは、同じパイプライン内の他のジョブとパラメーターを共有できるのは、それらがシーケンス内でリンクされている場合に限ります。同様に、パイプラインと構成は、ビルドチェーン内でリンクされている場合にのみ、互いのパラメーターにアクセスできます。

ジョブパラメーターにアクセスする

パイプラインジョブは、 job.<job_ID>.<param-name> 構文を使用して、先行するジョブパラメーターの値を取得できます。

jobs:
  Job1:
    name: Job 1
    steps:
      - type: script
        script-content: |-
          echo "Print Job1 parameter: %env.ParamJobA%"    # prints 'foo'
    parameters:
      env.ParamJobA: foo
  Job2:
    name: Job 2
    dependencies:
      - Job1
    parameters:
      env.ParamJobB: '%job.Job1.env.ParamJobA% bar'
    steps:
      - type: script
        script-content: |-
          echo "Print parameter from upstream Job: %job.Job1.env.ParamJobA%"     # prints 'foo'
          echo "Print modified parameter: %env.ParamJobB%"    # prints 'foo bar'

   

同じチェーン内の他のパイプラインや構成は、上流パイプラインのジョブパラメーターにアクセスできません。必要に応じて、ジョブパラメーターをパイプラインの出力パラメーターに割り当てることができます。

jobs:
  Job1:
    name: Job 1
    parameters:
      jobParam: foo
output-parameters:
  PipelineOutputParam: %job.Job1.jobParam%

   

構成パラメーターとパイプラインパラメーターにアクセスする

下流の構成またはパイプラインと構成 / パイプラインパラメーターを共有するには、そのパラメーターが出力パラメーターである必要があります。この場合、下流の構成またはパイプラインは、 dep.<config-or-pipeline-ID>.<parameter-name> 構文を使用してその値を読み取ることができます。

object Upstream : BuildType({
    name = "Upstream config"

    params {
        param("inputParam", "foo")    // Input parameter, cannot be shared
    }

    outputParams {
        // Output parameter, accessible via the 'dep.' prefix
        // Modified value of an input parameter
        param("outputParam", "%inputParam% bar")
    }
})

object Downstream : BuildType({
    name = "Downstream config"

    steps {
        script {
            id = "simpleRunner"
            // Prints 'foo bar'
            scriptContent = "echo ${Upstream.depParamRefs["outputParam"]}"
        }
    }

    dependencies { snapshot(Upstream) { }}
})

   

出力パラメーターは下流のオブジェクトからは参照できますが、自身の親構成やパイプラインでは使用できません。

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%"

   

構成のすべての入力パラメーターを公開する

ビルド構成では、新しい出力パラメーターを追加ダイアログに二つのオプションがあります: 値を手動で入力するか、既存の入力パラメーターをそのまま共有するかです。必要な入力パラメーターを選択すると、TeamCity は %inputParameter% 値を持つ出力パラメーターを作成します。

すべてのパラメーターは他のビルド構成で使用できます設定が有効になっている場合、各入力パラメーターを個別に共有する必要はありません。すべてのパラメーターが自動的に公開され、 dep.<config-ID>.<parameterName> 構文を使用して参照できます。

この設定は下位互換性のためにデフォルトで有効になっています。ただし、以下の手順を実行することを強くお勧めします。

入力パラメーターが他の構成で使用されているすべてのケースを確認します。
共有し続けたい入力パラメーターを新しい出力パラメーターで参照して公開します。
すべてのパラメーターは他のビルド構成で使用できますの設定を無効にします。

こうすることで、構成を簡単に保守できる状態に保てます: 必要に応じて入力パラメーターを編集および削除でき、これらのパラメーターを 依存… 構文で使用していたダウンストリーム構成を誤って壊すことがありません。さらに、共有されるように設計されていない非表示パラメーターを非表示のままにすることで、セキュリティが向上します。

アップストリームオブジェクトのパラメーターをオーバーライドする

下流の構成 / パイプラインは、 dep.<source-object-ID>.<parameter-name> を介して上流の構成 / パイプラインからパラメーターを読み取ることができます。 override.dep. 接頭辞を追加すると、その逆の操作、つまり直接的または間接的に依存するエンティティから上流パラメーターの値を上書きすることができます。

次の例は、2 つのオブジェクトがパラメーター値を交換する様子を示しています。

ビルドチェーンには、アップストリームパイプラインとダウンストリームビルド構成という 2 つのオブジェクトが含まれています。
パイプラインは、デフォルト値が foo である入力パラメーターを宣言します。パイプラインが単独で実行される場合、この値がビルドスクリプトで使用されます。
パイプラインがビルドチェーンの一部として実行される場合 (構成のスナップショット依存関係によってトリガーされます)、ダウンストリーム構成はこのパラメーターを上書きし、 bar に設定します。
パイプラインの出力パラメーターは入力パラメーターを参照するため、更新された値も報告します。

つまり、ダウンストリーム構成は override.dep. を介して bar をパイプライン入力に書き込み、パイプラインはそれを出力パラメーターを通して公開し、ダウンストリーム構成は dep. を介してそれを読み取ることができます。

# Upstream pipeline
jobs:
  Job1:
    name: Job 1
    steps:
      - type: script
        # Prints "foo" if the pipeline runs alone
        ## Or "bar" if runs in a chain
        script-content: 'echo "Input param: %PipelineInputParam%"'
parameters:
  PipelineInputParam: foo
output-parameters:
  # Output parameter shares input parameter as is
  PipelineOutputParam: '%PipelineInputParam%'


  

// Downstream configuration
object DownstreamConfig : BuildType({
    name = "Downstream build configuration"
    params {
        // Overrides the pipeline input parameter
        param("override.dep.MyProject_UpstreamPipeline.PipelineInputParam", "bar")
    }

    steps {
        script {
            id = "simpleRunner"
            // Prints "bar"
            scriptContent = """echo "${UpstreamPipeline.depParamRefs["PipelineOutputParam"]}""""
        }
    }
    dependencies { snapshot(UpstreamPipeline) { }}
})

  

送信側と受信側の型は関係ありません。この例では、ビルド構成がパイプラインパラメーターを上書きしていますが、パイプラインからビルド構成、パイプラインからパイプライン、ビルド構成からビルド構成など、どのような組み合わせでも同じ構文と動作が適用されます。

ワイルドカード

dep. パラメーターは正確なソースオブジェクト ID を必要としますが、 override.dep. パラメーターは ID の一部または全部をアスタリスク (*) で置き換えることができます。これにより、複数の一致するオブジェクトの入力パラメーターを一度に上書きすることが可能になります。

例えば、.NET プロジェクトをビルドする三つの構成を持ち、最上位に複合構成 (お名前は "Build All") があるビルドチェーンを考えてみます。各ビルド構成には、 build.mode パラメーターがあり、コンパイラーモードを設定して、値を デバッグ または リリース のいずれかにします。

「すべてビルド」からチェーン全体を実行する場合、現在のモードを維持するか、3 つの構成すべてに対して一度にモードを変更できます。これを行うには、3 つの個別の override.dep.<config-ID>.build.mode パラメーターではなく、1 つの override.dep.*.build.mode パラメーターを使用します。

// "Build All" composite configuration
object OverrideWildcard_BuildAll : BuildType({
    id("BuildAll")
    name = "Build All"
    type = BuildTypeSettings.Type.COMPOSITE

    params {
        // The "select" parameter with an extra "Default" value
        // Writes the same value to all upstream "build.mode" parameters
        select("override.dep.*.build.mode", "Default",
            options = listOf("<current setting>" to "Default", "Release", "Debug"))
    }

    dependencies {
        snapshot(BuildDmg) {}
        snapshot(BuildExe) {}
        snapshot(UnitTests) {}
    }
})

// Regular build/test configurations
object BuildDmg : BuildType({
    id = AbsoluteId("BuildDmg")
    name = "Build dmg"

    params {
        // The default mode is "Release"
        // Other configurations can have this set to "Debug"
        // Note there's no "Default" option
        select("build.mode", "Release",
            options = listOf("Debug", "Release"))
    }
    
    steps {
        csharpScript {
            name = "Set default debug mode"
            id = "Set_default_debug_mode"
            // If "Build All" set the parameter to "Default"...
            conditions {
                equals("build.mode", "Default")
            }
            // ...then send a service message to revert it back to "Release"
            content = """
            Console.WriteLine("The build.mode parameter was set to 'Default'.");
            Console.WriteLine("Setting the build mode to 'Release'...");
            Console.WriteLine("##teamcity[setParameter name='build.mode' value='Release']");
        """.trimIndent()
            tool = "%teamcity.tool.TeamCity.csi.DEFAULT%"
        }

        dotnetBuild {
            // TODO
        }
    }
})

   

競合の解決

パラメーターが、異なる構成またはパイプラインに属する複数の override.dep. パラメーターによって編集された場合、TeamCity は最後に実行されたエンティティによる最新の編集を適用します。

ConfigD (runs last, triggers the chain)
+------------------------------------------+
| override.dep.ConfigA.Fruit = "pear"      |
+------------------------------------------+
                 │
                 ▼
ConfigC (runs third)
+------------------------------------------+
| override.dep.ConfigA.Fruit = "orange"    |
+------------------------------------------+
                 │
                 ▼
ConfigB (runs second)
+------------------------------------------+
| override.dep.ConfigA.Fruit = "banana"    |
+------------------------------------------+
                 │
                 ▼
ConfigA (runs first)
+------------------------------------------+
| Fruit = "apple"                          |
+------------------------------------------+

Final value in ConfigA: "pear"

   

それ以外の場合、編集が複数の同一レベルのエンティティによって行われた場合は、ターゲットパラメーターは元の値を保持します。

特記事項

出力パラメーターは override.dep. パラメーターを介して編集することはできません。
override.dep. パラメーターは、ターゲット構成またはパイプライン内の既存のパラメーターを更新するだけで、不足しているパラメーターを作成することはありません。さらに、すでに同じ値を持つアップストリームパラメーターは強制的に更新されないため、TeamCity は以前のビルドを再利用できます。
パイプラインでは、パイプラインレベルのパラメーターのみが override.dep. という接頭辞を持つことができます。ジョブパラメーターはリモートパラメーターを変更できません。
jobs: Job1: name: Job 1 parameters: # Ignored override.dep.TargetID.myParam: foo dependencies: - TargetID parameters: # Applied override.dep.TargetID.myParam: bar
パイプラインパラメーターをオーバーライドする場合、 override.dep.*.paramName はスコープに関係なく任意の paramName を更新します: パイプライン入力とジョブパラメーターの両方が影響を受けます。
パラメーター参照を渡すと、その参照はパラメーター値が編集されるエンティティではなく、この override.dep. を所有するエンティティ内で解決されます。解決できない場合は、参照はプレーンテキストとして渡され、ビルドログに「パラメーターが完全に解決されていません」という警告が表示されます。
object UpstreamConfig : BuildType({ name = "Upstream config" params { param("bar", "default") param("foo", "default") } steps { script { id = "simpleRunner" scriptContent = """ echo "%foo%" // Prints "Downstream config" echo "%bar%" // Prints "%invalid%" """.trimIndent() } } }) object DownstreamConfig : BuildType({ name = "Downstream config" params { param("override.dep.UpstreamConfig.foo", "%system.teamcity.buildConfName%") // The name of THIS configuration param("override.dep.UpstreamConfig.bar", "%invalid%") // Unresolved } dependencies { snapshot(UpstreamConfig) { } } })
パラメーター参照は、アップストリームのビルドが実際に開始される前に解決されることに注意してください。その時点で、すべてのパラメーターの値はパイプライン / 構成設定で割り当てられているか、カスタムビルドを実行するダイアログを介して渡されている必要があります。ビルド中に計算されたパラメーターを参照した場合、値は渡されません。

'reverse.dep.' パラメーター

override.dep.<target-ID>.<parameter-name> 構文は TeamCity 2026.1 で導入されました。それ以前のバージョンでは、上流パラメーターは同様の reverse.dep.<target-ID>.<parameter-name> 構文で変更されていました。

逆依存。 も引き続きサポートされていますが、動作がよりシンプルで予測しやすい override.dep. をお勧めします。

override.dep. とは異なり、 逆依存。 はパラメーター参照を解決せず、そのまま渡すため、上流の構成やパイプラインが一部のビルドエージェントと互換性がなくなる可能性があります。
逆依存。 はさらに影響範囲が広く、ターゲット構成またはパイプラインに一致するパラメーターがない場合、TeamCity がパラメーターを作成します。一方、 override.dep. は既存のパラメーターのみを更新し、一致するパラメーターがないエンティティを無視します。新しいパラメーターを追加すると、" 適切なビルドがある場合は新しいビルドを実行しない" スナップショット依存関係ポリシーが無効になり、アップストリームビルドが再利用されなくなるため、この点にも注意してください。
逆依存。 はより複雑な競合解決方法を使用します。複数のエンティティが同じパラメーターを変更する場合、TeamCity は override.dep. と同様に、まず最後に実行された構成またはパイプラインを優先します。競合するエディターが同じレベルにある場合、TeamCity はターゲット ID の詳細度を比較し、最も具体的な ID を持つパラメーターが優先されます。
Config A +-----------------------------------------------------------+ | person = "Mary" | +-----------------------------------------------------------+ ┌────────────────────├───────────────────────┐ ▼ ▼ ▼ Config B Config C Config D +----------------+ +----------------+ +----------------+ | reverse.dep. | | reverse.dep. | | reverse.dep. | | ConfigA.person | | Conf*.person | | *.person | | = John | | = Mike | | = Jane | +----------------+ +----------------+ +----------------+ └─────────────────────├───────────────────────┘ Run all ▼ +-----------------------------------------------------------+ | composite configuration | | depends on: ConfigB, ConfigC, ConfigD | +-----------------------------------------------------------+ Config B: fully clarified target ID Config C: ID partially replaced with a wildcard Config D: wildcard instead of target ID Final value in ConfigA: "John" (Config B)
最後に、競合する編集が、同じレベルのエンティティから、同程度に具体的な ID で行われた場合、TeamCity はターゲットパラメーターを変更せず、競合する一意の値ごとに conflict.<sender_config_ID>.paramName パラメーターを追加します。

2026 年 9 月 11 日