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
CircleCI projects have pipelines and trigger.
-
Pipelines define the various CI/CD 'units' of work that make up your project.
-
Triggers define when and how to initiate a pipeline.
Configure triggers under Trigger a pipeline page.
. You can configure triggers to initiate pipelines on a variety of events. This page focuses on events from GitHub, but you can find the full list of events that can trigger a pipeline on theFor a full list of GitHub trigger event options, see Supported trigger options.

When you create or set up a project in CircleCI you will 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.
To find out which GitHub integration type you have, check your Organization slug at . OAuth authenticated orgs are structured as follows:
An organization slug for a GitHub App integration is in the following format:
|
If your CircleCI organization is integrated with GitHub only through the GitHub App (see tip above), 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
.
If your CircleCI org is integrated via GitHub OAuth (see tip above), an org admin can install the CircleCI GitHub App to enable the full range of GitHub trigger events, as well as all other functionality enabled by the GitHub App. Installing the CircleCI GitHub App is a one-time action. For more information, see the GitHub OAuth integration overview.
Supported trigger options
Regardless of your chosen trigger option, CircleCI will never trigger a pipeline for the following:
GitHub App pipelines are also never triggered on 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.
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.