CircleCI Logo
Navigation Menu Icon

Set up triggers

Language Icon 1 day ago · 11 min read
Cloud Server v4+
Contribute Go to Code

Triggers are configurable rules that determine when to automatically run a pipeline based on specific events and conditions.

A pipeline can have one or more triggers, which are associated with events from a source of change. The most common type of trigger is a VCS event, for example, a push to a branch on a GitHub repository. Any system that can emit outbound webhooks can be set up as a trigger. A trigger can have only one pipeline but a pipeline can have multiple triggers.

A trigger kicks off a pipeline to run the workflows defined in your connected config source.

Add a trigger

Bitbucket Cloud triggers are created automatically when setting up a project and they cannot be edited. The only additional trigger types available for Bitbucket Cloud pipelines are scheduled triggers.
Using CircleCI server? The Pipeline and Trigger pages under Project Settings and pipeline and trigger add/edit functionality is not available. CircleCI server pipelines are set up when a project is set up and cannot be edited. CircleCI server requires CircleCI configuration files to be stored in the same repository as your code at .circleci/config.yml.

The pipeline and trigger options and features available to you depend on how your code is integrated and where it is stored. For a feature availability overview, see the VCS integration overview page.

Triggers are available in the following types:

  • VCS triggers.

  • Custom webhooks used for triggering pipelines from external services.

  • Schedule triggers.

To add a trigger for a pipeline, follow these steps:

  • GitHub App

  • Custom webhook

  • GitLab

  • Bitbucket Data Center

  • Scheduled

When the CircleCI GitHub App is installed for your organization, GitHub starts to send events for the repositories you have granted access to. CircleCI can listen for push and pull request events. When a trigger is created, CircleCI has enough information to use the event data to determine if a pipeline should be triggered.

Add a trigger

  1. In the CircleCI web app, select your org from the org cards on your user homepage.

  2. Select Projects from the sidebar and locate your project from the list. You can use the search to help.

  3. Select the ellipsis more icon next to your project and select Project Settings.

  4. Select Project Setup in the sidebar.

  5. Select GitHub trigger + at the bottom of the pipeline box.

  6. Choose when top run the pipeline by selecting an option from the Event menu.

    Using multiple pipelines and triggers, you can build different pipelines for different events, For example, you could have:

    • A build-test pipeline that runs on every push. Select "All pushes".

    • A e2e-tests pipeline, longer and more costly, that runs once when the PR is taken out of draft. Select "PR marked ready for review".

    • A teardown-env pipeline that runs when a PR is merged. Select "PR merged".

    For a full list, see the GitHub trigger event options page.

    • The Event Source defaults to the repository associated with the pipeline. You can change the event source to a different repository if you wish. If you do change the event source so that it does not match the pipeline’s config/checkout source an option will appear to specify which branch in the config/checkout source repository you wish to use for the trigger.

  7. Select Save

To verify your trigger is set up correctly, trigger an event from your repository.

Setting up a custom webhook trigger allows you to trigger pipelines from external services. Any service that can emit a webhook or make a cURL request can be set up in this way to trigger a pipeline. For more information, see the Triggers overview page.

To add a custom webhook trigger, follow these steps:

  1. In the CircleCI web app, select your org from the org cards on your user homepage.

  2. Select Projects from the sidebar and locate your project from the list. You can use the search to help.

  3. Select the ellipsis more icon next to your project and select Project Settings.

  4. Select Project Setup in the sidebar.

  5. If there is already a GitHub App pipeline set up that you want to trigger with your custom webhook, proceed to the Triggers step below (step 5). If not, select Add Pipeline. You can find guidance on setting up a pipeline in the Pipelines overview and setup page.

    If you have not installed the CircleCI GitHub App into your GitHub organization you will be prompted to do so. Installing the GitHub App is a one-time step that can be done by an organization admin. Once installed, further GitHub App pipelines can be set up without this installation step. For a detailed guide to using both OAuth and GitHub App integrations, see the Using the CircleCI GitHub App in an OAuth organization page. If you run into issues when installing the GitHub App, for example, App looks installed on GitHub, but does not show up on CircleCI, submit a request through this form.

  6. Select Custom webhook + at the bottom of the pipeline box.

  7. Enter a descriptive name for the webhook event.

  8. Enter the name of the event source for the trigger. For example, if you are setting up a custom webhook to run pipelines on events from Datadog, enter "Datadog" here.

  9. Enter the branch to use to fetch your config file and checkout your code when a Custom Webhook is received.

    screenshot showing adding a custom webhook trigger

  10. Select Save.

  11. You will see a webhook endpoint URL and secret. You can use these to set up your webhook trigger from your external source. Copy the Webhook URL and use it in your trigger source appended with the secret.

    The secret will not be shown again so be sure to copy the URL before clicking Done.

To verify your trigger is set up correctly, trigger an event from your third party system.

When a trigger is created, CircleCI registers a webhook with GitLab. Push events from GitLab are sent to CircleCI. CircleCI then uses the event data to determine if a pipeline should run, and if so, which pipeline should be run.

In addition to a pipeline, each trigger includes the webhook URL, and in this scenario, a CircleCI-created GitLab token. The webhook URL and GitLab token are used to securely register the webhook within GitLab in order to receive push events from your GitLab repository. You can view webhooks for a project in GitLab at Settings  Webhooks.

Add a trigger

To add a trigger for a pipeline, follow these steps:

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

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

  3. Select Triggers in the sidebar.

  4. Select Add Trigger.

  5. Select the same location in the "Connect to" dropdown menu that you selected for your pipeline (for example, GitLab).

  6. Select Next.

  7. Complete the form fields and options:

    • Give your trigger a descriptive name.

    • Authorize your connection if this is not already showing with a check mark passed icon (Not required for custom webhooks).

      For GitLab self-managed you can enter the URL for an instance you have previously set up with CircleCI. You will need to enter the relevant personal access token again here to authorize the connection.

    • Select your repository from the dropdown menu. This should match the repository your pipeline is connected to (not required for custom webhooks).

    • Choose your pipeline from the "Choose config to run" menu.

    • (Optional) You can configure trigger filters to configure the event types that will trigger the pipeline. For more information, see the GitLab trigger options page.

  8. Select Save

    When setting up a trigger you will see a modal titled Webhook URL requesting that you set up a webhook in GitLab. You do not need to take action. The webhook is set up automatically by CircleCI. This is a known issue and will be fixed.

To verify your trigger is set up correctly, trigger an event from your repository.

For steps to add a trigger for a pipeline using Bitbucket Data Center, see the Bitbucket Data Center page.

This feature is supported for orgs that use OAuth authentication.

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>

This feature is not supported if your organization slug is in the following format:

  • circleci/<UID>.

For an overview of feature support, see the VCS integration overview page.

  1. In the CircleCI web app, select your org from the org cards on your user homepage.

  2. Select Projects from the sidebar and locate your project from the list. You can use the search to help.

  3. Select the ellipsis more icon next to your project and select Project Settings.

  4. Select Triggers in the sidebar.

  5. Select Add Trigger.

    The "Pipeline to run" menu only shows the OAuth pipelines, you cannot schedule GitHub App, GitLab or Bitbucket Data Center pipelines.

    • Give your trigger a descriptive name.

    • Enter an optional trigger description.

    • Select the pipeline to run.

    • Select a release frequencies (weekly/monthly, which days/months/time etc.).

    • Enter a branch or tag name to determine when to trigger the pipeline.

    • Optionally, enter pipeline parameters. If you declare pipeline parameters in the form, you need to make sure they are configured in your project’s .circleci/config.yml. See the Pipeline values and parameters page for more information.

    • Select an actor to initiate the trigger.

  6. Define the new schedule by filling out the form, then select Save Trigger.

The form also provides the option of adding pipeline parameters, which are typed pipeline variables that you declare at the top level of a configuration.

If you would like to manage common schedules for multiple workflows, you will need to manually set this in your .circleci/config.yml file. See the Schedule pipelines with multiple workflows page for examples.

Next steps

Find out more about triggering pipelines in the Triggers Overview.