TriggerPipeline

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

Tag	Description of usage	Required/Optional
`integrations`	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
`pipelineName`	The name of the pipeline that you want to trigger	Required
`stepName`	The name of the step that you want to trigger	Required
`branchName`	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
`projectKey`	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

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
`onStart`	Commands to execute in advance of the native operation. This is the ideal place to utilize the `set_trigger_payload` utility function to add custom step- and pipeline-level variables to your target.	Optional
`onSuccess`	Commands to execute on successful completion	Optional
`onFailure`	Commands to execute on failed completion	Optional
`onComplete`	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

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 example shows how to configure a TriggerPipeline step.

This example requires a JFrog Platform Access Token integration.

pipelines:
  - name: top_pipeline
    steps:
      - name: scan_controller
        type: TriggerPipeline
        configuration:
          pipelineName: scanner_pipeline
          stepName: scan_it
          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"

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)