GitHub trigger event options
When you create a trigger for a GitHub App pipeline, you can choose from a set of trigger options that are based on GitHub App events and their properties. Using GitHub App trigger options you can trigger pipeline on non-push events.
Introduction
When you set up a project in CircleCI you will also set up your first pipeline and trigger. This first trigger is, by default, an "all push" trigger, which corresponds to the GitHub App push event. If you have a GitHub App account with CircleCI, you will see trigger options when creating a project in the CircleCI web app, and you have the option to change the trigger options for your first trigger. You can also set up additional triggers during project creation, or setup/edit later in your .
![Create a project trigger and access trigger options](/docs/assets/img/docs/triggers/create-project-run-on.png)
Once your project is set up you can create additional pipelines and triggers ( Supported trigger options.
). You can configure your triggers to initiate pipelines on a variety of events, including non-push events, for example, a pull request being opened, or refined push events, for example, only pushes to a default branch, or pushes to a tag. For a full list see![Set a trigger option for a project trigger](/docs/assets/img/docs/triggers/run-on-open.png)
Supported trigger options
Regardless of your chosen trigger option, CircleCI will never trigger a pipeline for the following:
|
GitHub App triggers allow you to define the work to do (pipeline) when an event takes place (trigger). GitHub App triggers are an orchestration tool available in CircleCI. You can access GitHub App trigger options using the "Run on" menu when setting up a trigger. The following preset trigger options are available:
-
All pushes: Trigger your pipeline on all pushes to your repo. All pushes corresponds to the GitHub App push event. No pipelines are triggered on push events when a branch or tag are deleted. No pipeline is triggered when a branch is created.
-
Tag pushes: Trigger a pipeline on pushes to tags only. When choosing this option, you will also need to define tag filters in your config file.
-
Pushes to default branch: Trigger a pipeline on pushes to the default branch only.
-
PR opened or pushed to, default branch pushes, tag pushes: Trigger a pipeline on pushes to a branch for which there is an open Pull Request (PR), when a PR is opened, pushes to any tag, and pushes to the default branch. This applies also if the PR is re-opened after being closed.
-
PR opened: Trigger a pipeline when a PR is opened. This applies also if the PR has been opened in draft. It does not apply if the PR is closed and then re-opened. See the GitHub docs for the pull request opened event.
-
PR merged: Trigger a pipeline when a PR is merged only. See the GitHub docs for pull request closed.
-
PR marked ready for review: Trigger a pipeline when a PR is taken out of draft mode and marked ready for review. See the GitHub docs for pull request review requested.
-
"run-ci" label added to PR: Trigger a pipeline when a label "run-ci" is added to a PR. See the GitHub docs for pull request labelled.
Due to a bug, repeated pull request events of the same type do not result in a build if the associated commit SHA has not changed. As an example, consider a trigger configured with the option "PR marked ready for review". Marking a PR as ready for review, then converting it to draft, then marking it as ready for review again will lead to only one pipeline to be triggered, not two. We are working to resolve this issue. |
Help us prioritize additional trigger options? We are working to expand the available events and conditions for you to choose from. Let us know which additional triggers your team needs by filling out this form. |
Two pipeline values are available for all GitHub App pipelines for you to use to further configure the workflows and jobs to run on specific events:
-
pipeline.event.name
-
pipeline.event.action
The available GitHub App options for these values are listed in the following table:
Trigger type | pipeline.event.name | pipeline.event.action |
---|---|---|
GitHub push |
|
|
GitHub pull request |
|
|
Config orchestration tools are available from within your pipelines are as follows:
-
Use filters to control when a workflow will run.
-
Use filters to control when a job will run.
-
Use requires to control job dependencies within workflows.
-
Use filters in steps to control what work is done within a job.
Quickstart: Create a trigger to initiate a pipeline when a PR is opened
Prerequisites
-
A CircleCI account. You can sign up for free at circleci.com.
-
Your CircleCI account must be linked to a GitHub account, either via GitHub OAuth or via the CircleCI GitHub App.
-
A GitHub App pipeline that you want to trigger when a PR is opened. You can find steps on the Pipelines and triggers overview page.
Steps
-
In the CircleCI web app select Projects in the sidebar
-
Find your project in the list, select the ellipsis () next to it and choose Project Settings.
-
Select Triggers in the sidebar.
-
Select Add Trigger.
-
Select GitHub App in the "Trigger type" menu and select Next.
-
Complete the form fields and options:
-
Authorize your connection if this is not already showing with a .
-
Give your trigger a descriptive name.
-
Select the trigger source repository.
-
Choose your pipeline from the "Choose pipeline to run" menu.
-
Expand the "Run on" menu and select "PR Opened", this means that the pipeline will trigger on the
pull_request
GitHub even with theopened
action (See the GitHub docs webhooks page for more information).Figure 3. Run on trigger options for GitHub App triggers -
If prompted, enter a Config branch. This is the name of the branch that should be used to fetch your config file when a pipeline is triggered. This field is only required if your config is stored in a repository that is not the source of your trigger.
-
If prompted, enter a Checkout branch. This is the name of the branch that should be used to check out your code when a checkout step is run. This field is only required if your chosen pipeline’s Checkout source repository is not the source of your trigger.
-
-
Select Save.
To verify your trigger is set up correctly, trigger an event (open a PR) from your repository.
FAQs
Can I combine multiple trigger options?
No, different trigger event options cannot be combined in a single trigger. However, you can create multiple triggers for the same pipeline that listen for events from the same repository, with each trigger using a different trigger event option.
For example, by having one trigger with the trigger option "PR opened" and a second trigger with the trigger option "PR merged", your pipeline will trigger whenever a PR is opened or merged.
Next steps
For more examples of using GitHub App trigger options, see the Orchestration cookbook.