Triggering Pipelines and Steps

To automate your pipelines, you will want to set them up to run whenever some event occurs. Those events might be:

A commit to a source code repository
A source code repository branch or pull request
Some other external event
At some regular time interval

Steps automatically execute when they are triggered by some change event in a resource. Your pipeline should be constructed so that when each step makes some change to a resource, that change triggers execution of the next step. In this way, all the steps of your pipeline will execute in sequence.

To trigger a step for execution:

Specify the triggering event(s) in a resource.
Specify that resource as an inputresource of a step.

The specified change in that resource will then automatically trigger the step to run. When that step is the first step in the pipeline, it will initiate the entire run of that pipeline.

Triggering On a Git Repository Change

A Git source code repository is represented by a GitRepo resource. The events that cause a GitRepo to trigger can be specified in the buildOn group of tags.

The most commonly used event for triggering a run of a pipeline is any commit to the Git repository. For this reason, the value of this tag defaults to true. So if that is the only event you want to trigger on, then you do not need to specify buildOn tags at all in the GitRepo resource.

Your GitRepo can be set to trigger on any of these buildOn events:

Tag	Default	Event
`branchDelete`	false	An existing branch is deleted
`commit`	true	A new commit to the Git repo Note that when this is set as `false`, the resource is not updated and the resource version is not created.
`pullRequestCreate`	false	A new pull request made to the Git repo
`pullRequestClose`	false	A pull request to the Git repo is closed
`releaseCreate`	false	A new release request made to the Git repo
`tagCreate`	false	Creation of a new tag ref in the Git repo

This example causes a GitRepo to trigger a run of the pipeline on either a pull request or a release request. Since commit is true by default, we must explicitly set it to false.

resources:
  - name: my_source_repo
    type: GitRepo
    configuration:
      gitProvider: myGitHub
      path: mycompany/myrepository
      branches:
        include: master
      buildOn:
        commit:                false
        pullRequestCreate:     true
        releaseRequestCreate : true

pipelines:      
    - name: pipeline_gitrepo_trigger
      steps:
      - name: gitrepo_trigger_step_1
        type: Bash
        configuration:
          inputResources:
            - name: my_source_repo
        execution:
          onExecute:
            - printenv                                  # A benign operation for the demo

Skipping a Git Repository Commit

If a specific commit should not trigger any runs for a GitRepo resource, include the text [skipRun] anywhere in the commit message and no runs will be triggered by that commit.

For example, to commit a change from the GitHub command line:

$ git commit -m "[skipRun] Fixed spelling errors in comments"
# Commits the tracked changes but does not trigger Pipelines.

The GitRepo resource will still be updated so that it will be current to the latest version of the repository for any Pipelines step that references that GitRepo resource.

The [skipRun] directive suppresses triggering only for a commit event. The GitRepo resource will still trigger on other buildOn events (such as a pull request) if those events are set to true.

Cancelling Previous Runs On a Git Repository Change

By default, when a GitRepo buildOn event (e.g., a commit) triggers a run for a pipeline that is already queued or is in-progress from a prior trigger, Pipelines will queue a new run of that pipeline. The new run executes after the prior run completes.

A GitRepo resource can be optionally configured to automatically cancel any queued or in-progress run that was triggered by the same GitRepo resource.

Your GitRepo can be set to cancel on any of thesecancelPendingRunsOnevents:

Tag	Default	Event
`newCommit`	false	commit: previous runs for the same branch are cancelled tag: previous runs for the same tag name are cancelled release: previous runs for the same release name are cancelled
`pullRequestUpdate`	false	previous runs for the same pull request number are cancelled

Tag

Default

Event

newCommit

false

commit: previous runs for the same branch are cancelled

tag: previous runs for the same tag name are cancelled

release: previous runs for the same release name are cancelled

pullRequestUpdate

false

previous runs for the same pull request number are cancelled

Runs will only be cancelled for change events of the same type. For example, a commit will only cancel runs triggered by previous commits to the same branch.

This example causes a GitRepo to cancel previous runs for pull requests when a new run is triggered for the same pull request. Runs are not triggered for commits.

resources:
  - name: my_source_repo
    type: GitRepo
    configuration:
      gitProvider: myGitHub
      path: mycompany/myrepository
      branches:
        include: master
      buildOn:
        commit: false
        pullRequestCreate: true
      cancelPendingRunsOn:
        pullRequestUpdate: true
pipelines:      
  - name: pipeline_gitrepo_trigger
    steps:
      - name: gitrepo_trigger_step_1
        type: Bash
        configuration:
          inputResources:
            - name: my_source_repo
        execution:
          onExecute:
            - printenv                                  # A benign operation for the demo

Triggering On a Webhook

You may trigger execution on receipt of a webhook from an external source.

Create an IncomingWebhook resource that is configured to use an Incoming Webhook Integration, then include it in the inputresources block of the step to trigger. Any payload from the webhook will be available in the resource's environment variable $res_<resource_name>_payload, which can be written to a file. You can then use the read_json utility function to retrieve individual elements from the JSON payload into environment variables.

resources:
  - name: incoming_basic_hook
    type: IncomingWebhook
    configuration:
      webhookName: in_hook_basic

pipelines:
  - name: incoming_webhook_demo
    steps:
      - name: start_by_hook
        type: Bash
        configuration:
          inputResources:
            - name: incoming_basic_hook
        execution:
          onExecute:
            - echo "job triggered by resource-> $step_triggered_by_resource_name"
            - echo "$res_incoming_basic_hook_payload" | jq '.' > payload.json
            - echo "$(read_json payload.json my.nested.object)"

Triggering On a Time Schedule

A common practice for many organizations is to perform regular nightly builds during off-peak usage hours. For example, you may wish to execute the run of pipeline every night at 3:00am.

To trigger at a specific time or at regular time intervals, use the CronTrigger resource to specify the time or interval. In this resource you can specify a cron expression string. When you specify the CronTrigger resource as an inputresource to the first step in a pipeline, the pipeline will automatically commence execution at that time or interval.

This example demonstrates use of a CronTrigger resource to trigger the execution of a single-step pipeline every 5 minutes.

resources:
  - name: cron_trigger
    type: CronTrigger
    configuration:
      interval: '*/5 * * * *'     # Every 5 minutes

pipelines:      
  - name: pipeline_scheduled_triggers
    steps:
      - name: step_1
        type: Bash
        configuration:
          inputResources:
            - name: cron_trigger
        execution:
          onExecute:
            - printenv