Sign in

v1

latestOpenAPI 3.0.3MIT2026-07-1411163326.7 KB
Trigger

Create trigger

Create a trigger for a given pipeline definition. Currently only supported for pipeline definitions where config_source.provider is github_oauth, github_app, github_server, or schedule. Share feedback about our Project Administration APIs.

post/projects/{project_id}/pipeline-definitions/{pipeline_definition_id}/triggers

Path parameters

project_idstring required

An opaque identifier of a project.

pipeline_definition_idstring required

An opaque identifier of a pipeline definition.

Request body

event_preset'all-pushes' | 'only-tags' | 'default-branch-pushes' | 'only-build-prs' | 'only-open-prs' | 'only-labeled-prs' | 'only-merged-prs' | 'only-ready-for-review-prs' | 'only-build-pushes-to-non-draft-prs' | 'only-merged-or-closed-prs' | 'pr-comment-equals-run-ci' | 'non-draft-pr-opened' | 'pushes-to-merge-queues'

The name of the event preset to use when filtering events for this trigger.

When event_source.provider is github_app or github_server, all preset values are supported.

When event_source.provider is github_oauth, this field is required and only the following values are accepted: all-pushes, only-build-prs.

Not applicable when event_source.provider is webhook or schedule.

checkout_refstring

The ref to use when checking out code for pipeline runs created from this trigger. Always required when event_source.provider is webhook or schedule. When event_source.provider is github_app or github_server, only expected if the event source repository (identified by event_source.repo.external_id) is different to the checkout source repository of the associated Pipeline Definition. Otherwise, must be omitted.

config_refstring

The ref to use when fetching config for pipeline runs created from this trigger. Always required when event_source.provider is webhook or schedule. When event_source.provider is github_app or github_server, only expected if the event source repository (identified by event_source.repo.external_id) is different to the config source repository of the associated Pipeline Definition. Otherwise, must be omitted.

event_namestring

The name of the triggering event. Required when provider is webhook or schedule. Should not be set for other providers.

disabledboolean

Whether the trigger should be disabled upon creation. Not supported for triggers where event_source.provider is github_oauth.

parametersobject

Pipeline parameters to pass when running pipelines from this trigger. Currently only supported for triggers where event_source.provider is schedule.

Example request

{
  "event_source": {
    "provider": "github_app",
    "repo": {
      "external_id": "some-repo-id"
    },
    "webhook": {
      "sender": "some-webhook-sender"
    },
    "schedule": {
      "cron_expression": "*/5 * * * *",
      "attribution_actor": "current"
    }
  },
  "event_preset": "all-pushes",
  "checkout_ref": "some-checkout-ref",
  "config_ref": "some-config-ref",
  "event_name": "some-event-name",
  "parameters": {
    "deploy_env": "staging"
  }
}

Response

Successful response.

idstring uuid

The unique ID of the trigger.

event_namestring

The name of the event that will trigger the pipeline.

event_preset'all-pushes' | 'only-tags' | 'default-branch-pushes' | 'only-build-prs' | 'only-open-prs' | 'only-labeled-prs' | 'only-merged-prs' | 'only-ready-for-review-prs' | 'only-build-pushes-to-non-draft-prs' | 'only-merged-or-closed-prs' | 'pr-comment-equals-run-ci' | 'non-draft-pr-opened' | 'pushes-to-merge-queues'

The name of the event preset to use when filtering events for this trigger.

When event_source.provider is github_app or github_server, all preset values are supported.

When event_source.provider is github_oauth, this field is required and only the following values are accepted: all-pushes, only-build-prs.

Not applicable when event_source.provider is webhook or schedule.

checkout_refstring

The ref to use when checking out code for pipeline runs created from this trigger. If empty, the ref provided in the trigger event is used.

config_refstring

The ref to use when fetching config for pipeline runs created from this trigger. If empty, the ref provided in the trigger event is used.

disabledboolean

Whether the trigger is disabled. Not supported for triggers where event_source.provider is github_oauth.

parametersobject

Pipeline parameters passed when running pipelines from this trigger. Currently only supported for triggers where event_source.provider is schedule.

Example response

{
  "event_name": "some event name",
  "event_source": {
    "provider": "github_app",
    "repo": {
      "full_name": "some-org/some-repo-name",
      "external_id": "some-repo-id"
    },
    "webhook": {
      "url": "https://some-webhook.invalid/some-endpoint?secret=some-secret",
      "sender": "datadog"
    },
    "schedule": {
      "cron_expression": "*/5 * * * *"
    }
  },
  "event_preset": "all-pushes",
  "checkout_ref": "some-checkout-ref",
  "config_ref": "some-config-ref",
  "parameters": {
    "deploy_env": "staging"
  }
}