Start Building for Free

Triggers overview

2 months ago3 min read
Server v4.x
Server v3.x
On This Page

Pipelines are triggered in response to actions or scheduled to run at specific times and frequencies. Each method of triggering a pipeline is described below.

Trigger a pipeline on push to your code repository

Once a project is hooked up to CircleCI, a pipeline is triggered each time a commit is pushed on a branch that has a .circleci/config.yml file included. Once the commit is pushed the running pipeline appears on the pipelines dashboard, which is accessible by selecting Dashboard from the left hand sidebar in the CircleCI web app.

Screenshot showing running pipelines in the CircleCI dashboard.
Figure 1. Pipeline running and visible on the dashboard

Trigger a pipeline from the CircleCI web app

In the CircleCI web app, when you have a specific branch selected, the Trigger Pipeline button becomes enabled:

  1. Select your branch using the branch filter at the top of the dashboard.

    screenshot showing location of branch filter on pipelines dashboard
  2. Click Trigger Pipeline. At this point you can choose whether you want to specify any pipeline parameters.

    screenshot showing the popup you will see when slicking the trigger pipeline button in the web app
  3. Click Trigger Pipeline again (or Cancel) and you will see your new pipeline start.

Trigger a pipeline using the API

  1. If you have not already, get set up to use API v2 by following the steps in the API Developers Guide.

  2. To trigger a pipeline from the command line using curl, copy and paste this sample request and replace the details in < > with your details, VCS can be gh or bb:

    curl -X POST<VCS>/<your-vcs-org-or-username>/<your-repo-name>/pipeline \
      --header "Circle-Token: $CIRCLE_TOKEN" \
      --header "content-type: application/json" \
      --data '{"branch":"<your-branch-name>"}'
  3. Head back to the CircleCI web app and see your pipeline running on the dashboard.

Trigger a pipeline from an inbound webhook

To trigger a pipeline from anywhere that can emit a webhook, or run a curl command, follow these steps:

  1. Navigate to Project Settings  Triggers and select Add Trigger.

  2. Select "Inbound Webhook" from the "Connect To" dropdown menu, and click Next.

    screenshot showing adding an inbound webhook trigger
  3. Fill in the details of your trigger source, trigger description, and config file path. Then, click Save.

  4. 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. The secret will not be shown again so be sure to copy the URL before clicking Done.

    screenshot showing inbound webhook trigger secret and URL

To trigger this webhook using curl, copy and paste the following sample request and replace <your-URL> and <your-secret> with the URL and secret that you generated in the previous step:

curl -X POST -H "content-type: application/json" '<your-URL>?secret=<your-secret>'

See our community forum for more details or how to use this functionality with a 3rd party service like DockerHub.

Trigger a pipeline from VS Code with unversioned config

Trigger pipelines from VS Code to iterate on your CircleCI config without committing your trial and error changes to your version control system. Run and validate your full pipeline, or select jobs and workflows to validate individually. View the results of your test runs in the extension pipelines panel or in the CircleCI web app, just the same as any other pipeline.

For full details, see the VS Code extension overview.

Screenshot showing the run panel

Schedule a pipeline

For non GitLab/GitHub App projects, scheduled pipelines allow you to trigger pipelines periodically based on a schedule. To get this set up for a project you can either use the CircleCI web app or use the API v2. For full details of both methods see the Scheduled Pipelines docs.

Next steps

Read about orchestrating elements of work within pipelines on the Using Workflows to Orchestrate Jobs page.

Suggest an edit to this page

Make a contribution
Learn how to contribute