Triggers overview

Cloud

Server v4+

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 available for GitLab integrations.

In the CircleCI web app, select your organization from your homepage, then select your project, either from your org homepage or select Projects from the sidebar for a full list. You will now be on your project’s pipelines page.
Select Trigger Pipeline.
Select the pipeline you want to trigger from the dropdown menu.
Select your config source branch. This tells CircleCI where (repo and branch) to find your pipeline config.
If your code is integrated via the GitHub App or Bitbucket Data Center, select your checkout source and branch. This tells CircleCI which code to check out when running a checkout step.

If your code is integrated via GitHub OAuth or Bitbucket Cloud, you can skip this step, the same location is used for both config and checkout source.
If you would like to specify any pipeline parameters, select Add + and enter the required fields.
Select Run Pipeline and you will see your new pipeline running in the web app.

Trigger a pipeline using the API

Triggering a pipeline via the CircleCI v2 API is not currently supported for GitLab projects.

This method is supported for GitHub (OAuth and App) and Bitbucket (Cloud and Data Center) orgs.

GitHub OAuth and Bitbucket Cloud pipelines can also be triggered using the Trigger a New Pipeline endpoint, which is described in the CircleCI server tab. However, the method outlined in this section is recommended.

Trigger a pipeline for a project using the v2 API endpoint https://circleci.com/api/v2/project/<project-slug>/pipeline/run.

If you have not already, get set up to use API v2 by following the steps in the API Developers Guide.
In the CircleCI web app select your organization. Over the next few steps you will collect the data you need to trigger your pipeline.
Find your project slug:
1. Select Projects in the CircleCI web app sidebar.
2. Find your project.
3. Select the ellipsis menu () and choose Project Settings.
4. Copy your project slug. Save this somewhere, you will need it later.
Find your definition ID:
1. You should be in project settings if you are following these steps in sequence. If not see previous steps to get there. Select Pipelines in the sidebar.
2. In the column Definition ID, select Copy for the correct pipeline. Save this somewhere, you will need it in the next step.

To trigger a pipeline from the command line using curl, copy and paste this sample request and replace the details in < > with your details. The key parameters is optional:

curl -X POST https://circleci.com/api/v2/project/<project-slug>/pipeline/run \
  --header "Circle-Token: $CIRCLE_TOKEN" \
  --header "content-type: application/json" \
  --data '{
  "definition_id": "<pipeline-definition-id>",
  "config": {"branch": "<your-branch-name>"},
  "checkout": {"branch": "<your-branch-name>"},
  "parameters": {"<param-name>": "<param-value>"}
  }'

To run a pipeline based on a tag instead of a branch, replace the config and/or checkout fields with:
```
  "config": {"tag": "<your-tag-name>"},
  "checkout": {"tag": "<your-tag-name>"}
```
Head back to the CircleCI web app and see your pipeline running on the dashboard.

Trigger a pipeline from a custom webhook

Custom webhooks are available for projects integrated via the GitHub App. Custom webhooks are not available on CircleCI server.

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:

In the CircleCI web app select Projects in the sidebar.
Find your project in the list, select the ellipsis (), select Project Settings, and select Pipelines in the sidebar.
If there is already a GitHub App pipeline set up and it uses the desired YAML configuration file, proceed to the Triggers step below (step 5). If not, select Set up pipeline. If there is a Connect button, select it and follow the steps to install the CircleCI GitHub App into your GitHub organization (this step is compatible with orgs that integrate with CircleCI’s GitHub OAuth app).
Name the new pipeline and select the repository where the CircleCI YAML configuration file is stored. Enter the file path (including the .circleci directory). The file path can be different than .circleci/config.yml (for example, .circleci/webhook.yml). Save the pipeline.
Select Triggers in the sidebar.
Select Add Trigger.
Select Custom Webhook from the dropdown menu.
Select Next.
Complete the form fields and options:
- Enter a descriptive name for the trigger. For example, if you are setting up a custom webhook to run pipelines on events from Datadog, enter "Datadog" here.
- (Optional) Add a description.
- In the field "Pipeline to run", at the bottom of the page, select the pipeline that you created in the step above.
- Enter the branch to use to fetch your config file when a Custom Webhook is received.
- Enter the branch to use to check out your code when using the checkout step in config. If your config is stored in the same repository as your code, then your Config branch and your Checkout branch should be the same.
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

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.

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.