Orchestration cookbook

6 days ago2 min read
Last updated • Read time
Cloud
This document is applicable to CircleCI Cloud

This cookbook contains "recipes" for common pipeline, workflow and job execution goals and patterns.

Trigger a pipeline when a PR is marked ready for review

Goal

You may wish to run a specific set of more credit-consuming tests only when a pull request is ready to be taken out of its draft state — when the PR is marked as ready for review. To do this, set up a trigger for your pipeline that triggers when a pull request is marked ready for review, as follows:

Steps

  1. Set up a GitHub App pipeline you want to trigger when a PR is marked ready for review. Steps for setting up a pipeline are available in the Pipelines and triggers overview page.

    Add pipeline options for GitHub App
    Figure 1. Add pipeline options for GitHub App
  2. Set up a trigger for your pipeline and select PR marked ready for review under the Run on menu. Steps for setting up a trigger are available in the Pipelines and triggers overview page.

    Run on trigger options for GitHub App triggers
    Figure 2. Run on trigger options for GitHub App triggers

Notes

  • This option is only available for GitHub App pipelines. If you have a GitHub OAuth integration you can install the GitHub App into your GitHub org and then create GitHub App pipelines. This is a quick one-time action, as described in the GitHub integration page.

Trigger a pipeline when a PR is merged

Goal

You may wish to trigger a specific pipeline when a pull request is merged, for example, to run clean-up/teardown scripts. To do this, set up a trigger for a "clean-up" pipeline that is triggered when a pull request is merged.

Steps

  1. Set up a GitHub App pipeline you want to trigger when a PR is merged. Steps for setting up a pipeline are available in the Pipelines and triggers overview page.

    Add pipeline options for GitHub App
    Figure 3. Add pipeline options for GitHub App
  2. Set up a trigger for your pipeline and select PR merged under the Run on menu. Steps for setting up a trigger are available in the Pipelines and triggers overview page.

    Run on trigger options for GitHub App triggers
    Figure 4. Run on trigger options for GitHub App triggers

Notes

  • This option is only available for GitHub App pipelines. If you have a GitHub OAuth integration you can install the GitHub App into your GitHub org and then create GitHub App pipelines. This is a quick one-time action, as described in the GitHub integration page.

Run a workflow only when a pull request is opened

Goal

You may wish to configure a workflow in your pipeline that will only run on a pipeline that is triggered when a pull request is opened. To do this you can use a workflow filter.

Steps

  1. Update your CircleCI config to include a workflow that you only want to run when a PR is opened.

    workflows:
      workflow-pr-open:
        # Only run this workflow when a PR is opened
        when: pipeline.event.name == pull_request and pipeline.event.action == opened
        jobs:
          - my-job-1
          - my-job-2

Notes

  • The pipeline.event.name and pipeline.event.action variables are only available for GitHub App pipelines. If you have a GitHub OAuth integration you can install the GitHub App into your GitHub org and then create GitHub App pipelines. This is a quick one-time action, as described in the GitHub integration page.