Triggers overview

Cloud

Server v4.x

Server v3.x

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

This feature is not yet available for GitLab or GitHub App accounts. To find out which GitHub account type you have, see the GitHub App integration page.

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

Select your branch using the branch filter at the top of the dashboard.
Select Trigger Pipeline. At this point you can choose whether you want to specify any pipeline parameters.
Select Trigger Pipeline again (or Cancel) and you will see your new pipeline start.

Trigger a pipeline using the API

Triggering a pipeline via the CircleCI v2 API is not currently supported for GitLab, GitHub App or Bitbucket Data Center projects. To find out if you authorized through the GitHub OAuth app or the CircleCI GitHub App, see the GitHub App integration page. Alternatively, for projects using GitHub App, the custom webhooks functionality provides similar capabilities.

For non GitLab/GitHub App projects, you can trigger a pipeline for a project using the Trigger a New Pipeline endpoint.

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

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 https://circleci.com/api/v2/project/<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>"}'

Head back to the CircleCI web app and see your pipeline running on the dashboard.

You can also specify pipeline parameters when triggering a pipeline using the API. For full details, see the API v2 Docs.

Trigger a pipeline from a custom webhook

Follow these steps to set up and test a custom webhook trigger for a pipeline from anywhere that can emit a webhook or run a curl command:

Selecting a custom webhook as a pipeline trigger is currently in open preview. This feature is only available for accounts that are integrated through the CircleCI GitHub App. To find out which GitHub account type you have, see the GitHub App integration page.

In the CircleCI web app select Projects in the sidebar.
Find your project in the list, select the ellipsis (), and select Project Settings.
Select Triggers in the sidebar.
Select Add Trigger.
Select Custom Webhook from the dropdown menu.
Select Next.
Complete the form fields and options:
- Give your trigger a descriptive name.
- (Optional) Add a description.
- Supply a path to a config.yml file and CircleCI will create a configuration source for you:
Select Save.
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.
You can now test your custom webhook trigger with curl. To trigger your pipeline, 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:

When triggering via curl, you must use a POST request with content-type: application/json.
```
curl -X POST -H "content-type: application/json" 'https://internal.circleci.com/private/soc/e/<your-URL>?secret=<your-secret>'
```

For more information on using custom and outbound webhooks, see the Use webhooks to integrate with services page. Also, 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

The ability to trigger a pipeline from VS Code with an unversioned config is currently in Open Preview.

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.

Schedule a pipeline

Scheduling a pipeline is not currently supported for GitLab, GitHub App or Bitbucket Data Center projects. To find out if you authorized through the GitHub OAuth app or the CircleCI GitHub App, see the GitHub App integration page.

For non GitLab/GitHub App/Bitbucket Data Center 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.