# Trigger a Pipeline — CircleCI

> Trigger a pipeline given a pipeline definition ID. Supports all integrations except GitLab. See the documentation

- Key: `circleci-trigger-pipeline`
- Type: Action (Write)
- Version: 0.0.3
- App: CircleCI (`circleci`) — https://pipedream.com/apps/circleci.md
- This page (HTML): https://pipedream.com/apps/circleci/actions/trigger-pipeline
- Hints: open-world
- Source: https://github.com/PipedreamHQ/pipedream/blob/master/components/circleci/actions/trigger-pipeline/trigger-pipeline.mjs

## Description

Trigger a pipeline given a pipeline definition ID. Supports all integrations except GitLab. [See the documentation](https://circleci.com/docs/api/v2/index.html#tag/Pipeline/operation/triggerPipelineRun)

## Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `projectSlug` | `string` | Yes | Project slug in the form vcs-slug/org-name/repo-name (found in Project Settings) |
| `definitionId` | `string` | Yes | The unique ID for the pipeline definition. This can be found in the page Project Settings > Pipelines. |
| `configBranch` | `string` | No | The branch that should be used to fetch the config file. Note that branch and tag are mutually exclusive. To trigger a pipeline for a PR by number use pull//head for the PR ref or pull//merge for the merge ref (GitHub only) |
| `configTag` | `string` | No | The tag that should be used to fetch the config file. The commit that this tag points to is used for the pipeline. Note that branch and tag are mutually exclusive. |
| `checkoutBranch` | `string` | No | The branch that should be used to check out code on a checkout step. Note that branch and tag are mutually exclusive. To trigger a pipeline for a PR by number use pull//head for the PR ref or pull//merge for the merge ref (GitHub only) |
| `checkoutTag` | `string` | No | The tag that should be used to check out code on a checkout step. The commit that this tag points to is used for the pipeline. Note that branch and tag are mutually exclusive. |
| `parameters` | `object` | No | An object containing pipeline parameters and their values. Pipeline parameters have the following size limits: 100 max entries, 128 maximum key length, 512 maximum value length. |

## Run it

**MCP**

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const accessToken = await pd.rawAccessToken

const transport = new StreamableHTTPClientTransport(
  new URL("https://remote.mcp.pipedream.net/v3"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "x-pd-project-id": process.env.PIPEDREAM_PROJECT_ID!,
        "x-pd-environment": "production",
        "x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
        "x-pd-app-slug": "circleci",
      },
    },
  },
)

const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)

const { tools } = await mcp.listTools()

// listTools() hands your model this tool's input schema, so it can
// fill the arguments itself:
const result = await mcp.callTool({
  name: "circleci-trigger-pipeline",
  arguments: {
    projectSlug: "Project Slug",
    definitionId: "Definition ID",
  },
})
```

**TypeScript**

```ts
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "circleci-trigger-pipeline",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    circleci: { authProvisionId: "apn_xxxxxxx" },
    projectSlug: "Project Slug",
    definitionId: "Definition ID",
  },
})

console.log(result)
```

**cURL**

```bash
curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
  -H "Content-Type: application/json" \
  -H "X-PD-Environment: production" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "external_user_id": "{external_user_id}",
    "id": "circleci-trigger-pipeline",
    "configured_props": {
      "circleci": { "authProvisionId": "apn_xxxxxxx" },
      "projectSlug": "Project Slug",
      "definitionId": "Definition ID"
    }
  }'
```

---

- App: https://pipedream.com/apps/circleci.md · All apps: https://pipedream.com/apps