Go to Application

GitHub trigger event options

16 days ago · 11 min read

Cloud

Contribute

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

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

To find out which GitHub integration type you have, check your Organization slug at Organization settings Overview. OAuth authenticated orgs are structured as follows:

github/<your-org-name> or gh/<your-org-name>
bitbucket/<your-org-name> or bb/<your-org-name>

An organization slug for a GitHub App integration is in the following format:

circleci/<UID>

If your CircleCI organization is integrated with GitHub only through the GitHub App, you will see trigger options when creating a project in the CircleCI web app. You have the option to change the trigger options for your first trigger when setting the project up. You can also set up additional triggers during project creation, or setup/edit later in your Project settings Project Setup.

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), you can configure new triggers and optionally remove the existing OAuth trigger through Project settings Project Setup.

Supported trigger options

Regardless of your chosen trigger option, CircleCI will never trigger a pipeline for the following:

On branch or tag deletion push events.

GitHub App pipelines are also never triggered on the following:

When a new branch is created if there are no new commits on the branch.

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 and 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 merged or closed: Trigger a pipeline when a PR is merged or closed. When this option is selected, pipelines will run by default on the base branch on the pull request, not on the head branch.
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.
Pushes to open non-draft PRs: Trigger a pipeline when there is a push to a branch with an open PR that is not in draft mode.

Forked pull requests never trigger GitHub App pipelines.

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.

The following two pipeline values are available for all GitHub App pipelines. Use these values to further configure your 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

Trigger type	`pipeline.event.name`	`pipeline.event.action`
GitHub push	`push`	`push`
GitHub pull request	`pull_request`	`opened` `synchronize` `reopened` `closed` `ready_for_review` `labeled`

GitHub push

push

GitHub pull request

pull_request

opened
synchronize
reopened
closed
ready_for_review
labeled

All pipelines triggered by pull request events also have the following pipeline values populated:

pipeline.event.github.pull_request.base.ref: the name of the base (or target) branch of the PR - that is the branch that will receive the changes.
pipeline.event.github.pull_request.head.ref: the name of the head branch of the PR - that is the branch containing the changes to be merged.
pipeline.event.github.pull_request.draft: a boolean value indicating whether the pull request is a draft.

Example: To trigger a pipeline on PR opened or pushed to, default branch and tag pushes, and ensure that it never runs if the event is associated with a draft PR, use the following:
```
workflows:
  my-workflow:
    when: pipeline.event.name == "api" or pipeline.event.name == "push" or  (pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.draft == false)
    jobs:
      - myjob
```
- The condition pipeline.event.github.pull_request.draft == false excludes draft PRs from triggering the workflow.
- pipeline.event.name == "api" ensures that the workflow runs when triggered manually via the web app or API.
- pipeline.event.name == "push" ensures that the workflow runs when triggered via push to the default branch.
pipeline.event.github.pull_request.title: the title of the pull request.
pipeline.event.github.pull_request.number: the numeric identifier of the pull request.
pipeline.event.github.pull_request.merged: a boolean that indicates whether the PR was merged or not.

These values are extracted directly from the GitHub event payload. The part after prefix pipeline.event.github.* matches the corresponding field in the pull request event structure described in the GitHub docs.

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 overview and setup page.

Steps

In the CircleCI web app, select your org from the org cards on your user homepage.
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
Select the ellipsis next to your project and select Project Settings.

You can also access project settings from each project overview page using the Settings button.
Select GitHub trigger + at the bottom of the pipeline box.
Choose "PR Opened" from the Event menu. This means that the pipeline will trigger on the pull_request GitHub event with the opened action (See the GitHub docs webhooks page for more information).

Figure 3. Trigger options under Project settings

.
- Select the Event Source repository from the dropdown. This defaults to the config source repository. If you change it to a repository that does not match the pipeline’s checkout source, you can specify a branch to be used for fetching config and code checkout.
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 the following:

One trigger with the trigger option "PR opened"
One 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.

[path]

[title]