TriggerPipeline

JFrog Pipelines Documentation

ft:sourceType
Paligo

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

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

waitForRunCompletion

Boolean value. When set as false, parent pipeline will not wait for the child pipeline to complete before executing. Default value is true.

Optional

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

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

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

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)