GitHub trigger event options

yesterday4 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

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

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

Once your project is set up you can create additional pipelines and triggers (Project settings  Triggers). 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 Supported trigger options.

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

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.