The TriggerPipeline native step will trigger another step and wait for the resulting run to complete before continuing. This allows you to embed another pipeline inside your own.
Note
This step type will utilize a build node to poll for the status of the triggered run until it is complete. Ensure that the capacity of your node pool is sufficient to support both pipelines executing in parallel.
For more information about using the
TriggerPipeline
native step, see Embedded Pipelines.
You can use the set_trigger_payload
utility function in the onStart
section of this step to set customized parameters for the pipeline that you wish to trigger. The set_trigger_payload
property allows modification and isn't restricted to read-only access. In addition, you can add pipelineVariables
, which will apply to all steps in the triggered run, as well as stepVariables
, which will apply only to the specified step.
Linux only
This step is supported for execution on Linux machines only. PowerShell support is not yet available.
YAML Schema
The YAML schema for the TriggerPipeline native step is as follows:
TriggerPipeline
pipelines: - name: <string> steps: - name: <string> type: TriggerPipeline configuration: #inherits all the tags from bash pipelineName: <string> # required stepName: <string> # required branchName: <string> # optional. recommended if target is multibranch. projectKey: <string> # optional. recommended if target belongs to a project. waitForRunCompletion: <boolean> # optional. default is true. integrations: - name: <JFrog Platform Access Token integration> # required execution: onStart: - echo "Preparing for work..." - set_trigger_payload stepVariables "test=true" - set_trigger_payload pipelineVariables "notify=true" "version=5.4.3" - export pipelines_poll_interval_seconds=30 # defaults to 10 onSuccess: - echo "Job well done!" onFailure: - echo "Something went wrong" - echo "Nested run status is: ${nested_run_status}" onComplete: - echo "Cleaning up"
Tags
name
An alphanumeric string (underscores are permitted) that identifies the step.
type
Must be TriggerPipeline
for this step type.
configuration
Specifies all configuration selections for the step's execution environment. This step inherits the Bash/ PowerShell step configuration tags, including these pertinent tags:
Tag | Description of usage | Required/Optional |
---|---|---|
| Specifies an JFrog Platform Access Token integration. This integration should contain a token that has the appropriate level of access to trigger the specified pipeline. | Required |
| The name of the pipeline that you want to trigger | Required |
| The name of the step that you want to trigger | Required |
| Boolean value. When set as | Optional |
| The name of the branch that you want to trigger. This should be used if your target pipeline comes from a multibranch pipeline source. | Optional May be required |
| The unique key of the Project that contains the pipeline that you want to trigger. This should only be used if your target pipeline belongs to a Project. | Optional May be required |
In addition, these tags can be defined to support the step's native operation:
Tags derived from Bash
All native steps derive from the Bash step. This means that all steps share the same base set of tags from Bash, while native steps have their own additional tags as well that support the step's particular function. So it's important to be familiar with the Bash step definition, since it's the core of the definition of all other steps.
execution
Declares collections of shell command sequences to perform for pre- and post-execution phases:
Tag | Description of usage | Required/Optional |
---|---|---|
| Commands to execute in advance of the native operation. This is the ideal place to utilize the | Optional |
| Commands to execute on successful completion | Optional |
| Commands to execute on failed completion | Optional |
| Commands to execute on any completion | Optional |
The actions performed for the onExecute
phase are inherent to this step type and may not be overridden.
environment variables
The TriggerPipeline step utilizes several new environment variables to provide as much information as possible.
These variables can be used to configure the behavior of the TriggerPipeline
step
variable name | value |
---|---|
pipelines_poll_interval_seconds | How frequently, in seconds, the step should poll for its nested run status. Defaults to 10 seconds |
These variables are injected into the environment of the target pipeline
variable name | value |
---|---|
parent_step_id | The unique ID of the TriggerPipeline step |
parent_step_name | The name of the TriggerPipeline step |
parent_step_url | The URL that links to the TriggerPipeline step |
parent_run_id | The unique ID of the run that the TriggerPipeline step belongs to |
parent_run_number | The run number of the run that the TriggerPipeline step belongs to |
These variables are exported into the TriggerPipeline
step environment after the target pipeline's run completes.
variable name | value |
---|---|
nested_run_status | The final status of the triggered run (can be success, failure, error, canceled, timeout, or skipped) |
nested_run_number | The run number of the triggered run. |
nested_run_duration_seconds | The total duration of the triggered run (in seconds) |
nested_run_url | The URL that links to the triggered step |
Examples
The following examples show how to configure a TriggerPipeline
step.
These examples require a JFrog Platform Access Token integration.
Example 1
pipelines: - name: top_pipeline steps: - name: scan_controller type: TriggerPipeline configuration: pipelineName: scanner_pipeline stepName: scan_it waitForRunCompletion: true integrations: - name: myPlatformToken environmentVariables: scan_target: default: "hello-world" allowCustom: true values: - "vault" - "redis" - "postgresql" - "hello-world" execution: onStart: - set_trigger_payload pipelineVariables "scan_target=${scan_target}" - set_trigger_payload stepVariables "notify=email" "uploadReport=true" onComplete: - echo "Final status is $nested_run_status" - name: scanner_pipeline steps: - name: scan_it type: Bash execution: onExecute: - echo "Image to scan is $scan_target." - echo "Triggered by parent step at $parent_step_url"
Example 2
resources: - name: propertyBag_e type: PropertyBag configuration: foo: bar - name: propertyBag1_e type: PropertyBag configuration: foo1: bar1 - name: propertyBag2 type: PropertyBag configuration: foo2: bar2 - name: propertyBag3 type: PropertyBag configuration: foo3: bar3 pipelines: - name: pipeline1 steps: - name: first_step type: TriggerPipeline configuration: pipelineName: pipeline2 stepName: first_step waitForRunCompletion: false integrations: - name: myPlatformToken execution: onStart: - echo "executing first_step $pipeline_name" - name: pipeline2 steps: - name: first_step type: TriggerPipeline configuration: pipelineName: pipeline3 stepName: first_step waitForRunCompletion: false integrations: - name: myPlatformToken execution: onStart: - echo "executing first_step $pipeline_name" - name: second_step type: TriggerPipeline configuration: inputSteps: - name: first_step pipelineName: pipeline4 stepName: first_step waitForRunCompletion: false integrations: - name: myPlatformToken execution: onStart: - echo "executing second_step $pipeline_name" - name: pipeline3 steps: - name: first_step type: TriggerPipeline configuration: pipelineName: pipeline4 stepName: first_step waitForRunCompletion: false integrations: - name: myPlatformToken execution: onStart: - echo "executing first_step $pipeline_name" - name: pipeline4 steps: - name: first_step type: TriggerPipeline configuration: pipelineName: pipeline5 stepName: first_step waitForRunCompletion: false integrations: - name: myPlatformToken execution: onStart: - echo "executing first_step $pipeline_name" - name: pipeline5 steps: - name: first_step type: TriggerPipeline configuration: pipelineName: pipeline6 stepName: first_step waitForRunCompletion: true integrations: - name: myPlatformToken execution: onStart: - echo "executing first_step $pipeline_name" - name: second_step type: TriggerPipeline configuration: inputSteps: - name: first_step pipelineName: pipeline7 stepName: first_step waitForRunCompletion: true integrations: - name: myPlatformToken execution: onStart: - echo "executing second_step $pipeline_name" - name: pipeline6 steps: - name: first_step type: Bash configuration: inputResources: - name: propertyBag3 execution: onExecute: - echo "executing pipeline6" - name: pipeline7 steps: - name: first_step type: Bash configuration: inputResources: - name: propertyBag3 execution: onExecute: - echo "executing pipeline7"
How it Works
When you use the TriggerPipeline native step in a pipeline, it performs the following functions in the background:
GET /projects (if projectKey is provided, the projectId is found)
GET /pipelines (find the pipeline by its name)
GET /pipelineSteps (find the step by its name)
POST /pipelineSteps/:id/trigger (trigger a run starting from the specified step)
GET /runs/:id (poll the run to check its status)