GitHub trigger event options

today4 min read
Last updated • Read time
Cloud
This document is applicable to CircleCI Cloud

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 Project settings  Triggers. 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 the Trigger a pipeline page.

For a full list of GitHub trigger event options, see Supported trigger options.

Set a trigger option for a project trigger
Figure 1. Trigger options under Project settings

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.

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 Project settings  Triggers.

Create a project trigger and access trigger options
Figure 2. Trigger options during project creation

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

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.

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 typepipeline.event.namepipeline.event.action

GitHub push

push

push

GitHub pull request

pull_request

  • opened

  • synchronize

  • reopened

  • closed

  • ready_for_review

  • labeled

Config orchestration tools are available from within your pipelines are as follows:

Quickstart: Create a trigger to initiate a pipeline when a PR is opened

Prerequisites

Steps

  1. In the CircleCI web app select Projects in the sidebar

  2. Find your project in the list, select the ellipsis () next to it and choose Project Settings.

  3. Select Triggers in the sidebar.

  4. Select Add Trigger.

  5. Select GitHub App in the "Trigger type" menu and select Next.

  6. 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 the opened action (See the GitHub docs webhooks page for more information).

      Run on trigger options for GitHub App triggers
      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.

  7. 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.