Overview

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.

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

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:

pipelines: 
  - name:   <string>
    steps:
      - name: <string>
        type: TriggerPipeline
        configuration:
          #inherits all the tags from bash; https://www.jfrog.com/confluence/display/JFROG/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"

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

projectKeyThe 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:

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:
TagDescription of usageRequired/Optional
onStartCommands 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
onSuccessCommands to execute on successful completionOptional
onFailureCommands to execute on failed completionOptional
onCompleteCommands to execute on any completionOptional


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 namevalue
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 namevalue
parent_step_idThe unique ID of the TriggerPipeline step
parent_step_nameThe name of the TriggerPipeline step
parent_step_urlThe URL that links to the TriggerPipeline step
parent_run_idThe unique ID of the run that the TriggerPipeline step belongs to
parent_run_numberThe 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 namevalue
nested_run_statusThe final status of the triggered run (can be success, failure, error, canceled, timeout, or skipped)
nested_run_numberThe run number of the triggered run.
nested_run_duration_secondsThe total duration of the triggered run (in seconds)
nested_run_urlThe 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)