Orchestration cookbook
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
-
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.
Figure 1. Add pipeline options for GitHub App -
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.
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.
To find out which GitHub integration type you have, check your Organization slug at
. OAuth authenticated orgs are structured as follows:-
github/<your-org-name>
orgh/<your-org-name>
-
bitbucket/<your-org-name>
orbb/<your-org-name>
An organization slug for a GitHub App integration is in the following format:
-
circleci/<UID>
-
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
-
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.
Figure 3. Add pipeline options for GitHub App -
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.
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.
To find out which GitHub integration type you have, check your Organization slug at
. OAuth authenticated orgs are structured as follows:-
github/<your-org-name>
orgh/<your-org-name>
-
bitbucket/<your-org-name>
orbb/<your-org-name>
An organization slug for a GitHub App integration is in the following format:
-
circleci/<UID>
-
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
-
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
andpipeline.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.To find out which GitHub integration type you have, check your Organization slug at
. OAuth authenticated orgs are structured as follows:-
github/<your-org-name>
orgh/<your-org-name>
-
bitbucket/<your-org-name>
orbb/<your-org-name>
An organization slug for a GitHub App integration is in the following format:
-
circleci/<UID>
-