<!-- BusyBot node reference — https://busybot.net/tools/circleci/ -->

> Node: CircleCI (`circleci`) · Action · v1
> Category: Development · Credentials: CircleCI API (`circleCiApi`)
> Updated: 2026-08-16

# CircleCI

> Get, list, and trigger CircleCI pipelines.

## Overview

CircleCI is a continuous integration and continuous delivery (CI/CD) platform. This tool allows you to retrieve pipeline information, list pipelines for a project, and trigger new pipeline runs via the CircleCI API v2. It supports projects hosted on GitHub and Bitbucket.

**Category:** Development  
**Tool Name:** `circleci`  
**Version:** 1

**Appearance:** Icon: `si-circleci` | Color: `#343434`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **CircleCI API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/circle-ci-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Pipeline | `pipeline` |

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Get | `get` | Get a pipeline |
| Get Many | `getAll` | Get many pipelines |
| Trigger | `trigger` | Trigger a pipeline |

### Parameters

#### Pipeline: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Provider | `options` | No | — | Source control system. |
| | | | | Options: `bitbucket`, `github` |
| Project Slug | `string` | No | — | Project slug in the form org-name/repo-name. Supports expressions like {{ $json.repo }}. |
| Pipeline Number | `number` | No | `1` | The number of the pipeline. Supports expressions. |

#### Pipeline: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Provider | `options` | No | — | Source control system. |
| | | | | Options: `bitbucket`, `github` |
| Project Slug | `string` | No | — | Project slug in the form org-name/repo-name. Supports expressions like {{ $json.repo }}. |
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `100` | Max number of results to return. _(shown when Return All is `false`)_ |
| Filters | `collection` | No | `{}` | Filters for the pipeline list. |
| — Branch | `string` | No | — | The name of a VCS branch to filter by. Supports expressions. |

#### Pipeline: Trigger

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Provider | `options` | No | — | Source control system. |
| | | | | Options: `bitbucket`, `github` |
| Project Slug | `string` | No | — | Project slug in the form org-name/repo-name. Supports expressions like {{ $json.repo }}. |
| Additional Fields | `collection` | No | `{}` | Additional fields for triggering a pipeline. |
| — Branch | `string` | No | — | The branch where the pipeline will run. Note that branch and tag are mutually exclusive. Supports expressions. |
| — Tag | `string` | No | — | The tag used by the pipeline. Note that branch and tag are mutually exclusive. Supports expressions. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

What happens to the input item's JSON depends on the operation, and the two behaviours are different — this matters when a downstream node still expects fields that arrived with the item.

| Operation | Output |
|-----------|--------|
| `get` | One item. The pipeline object from the API is **merged onto** the input item's JSON, so incoming fields pass through. |
| `trigger` | One item. The trigger response from the API is **merged onto** the input item's JSON. |
| `getAll` | **Fans out** — one output item per pipeline. Each output item's JSON is the pipeline object itself and **replaces** the input JSON; nothing the item arrived with is carried over. When no pipelines match, the input item produces no output items at all. |

Binary data on the input item is forwarded in every case.

Pipeline fields come straight from the CircleCI API v2 response — reference them downstream by expression, e.g. `{{ $json.id }}` or `{{ $json.state }}`.

## Usage Examples

- Get a specific pipeline by number
- List all pipelines for a project
- List pipelines filtered by branch
- Trigger a new pipeline run on a branch
- Trigger a pipeline build for a specific tag

## Example Configuration

Get one pipeline by its number:

```json
{
  "type": "circleci",
  "parameters": {
    "resource": "pipeline",
    "operation": "get",
    "vcs": "github",
    "projectSlug": "myorg/myrepo",
    "pipelineNumber": 123
  }
}
```

List every pipeline for a project:

```json
{
  "type": "circleci",
  "parameters": {
    "resource": "pipeline",
    "operation": "getAll",
    "vcs": "github",
    "projectSlug": "myorg/myrepo",
    "returnAll": true
  }
}
```

List up to 25 pipelines on one branch:

```json
{
  "type": "circleci",
  "parameters": {
    "resource": "pipeline",
    "operation": "getAll",
    "vcs": "github",
    "projectSlug": "myorg/myrepo",
    "returnAll": false,
    "limit": 25,
    "filters": {
      "branch": "develop"
    }
  }
}
```

Trigger a pipeline on a branch:

```json
{
  "type": "circleci",
  "parameters": {
    "resource": "pipeline",
    "operation": "trigger",
    "vcs": "github",
    "projectSlug": "myorg/myrepo",
    "additionalFields": {
      "branch": "{{ $json.branch }}"
    }
  }
}
```

Trigger a pipeline for a tag on a Bitbucket project:

```json
{
  "type": "circleci",
  "parameters": {
    "resource": "pipeline",
    "operation": "trigger",
    "vcs": "bitbucket",
    "projectSlug": "myorg/myrepo",
    "additionalFields": {
      "tag": "v2.1.0"
    }
  }
}
```

Check the ten most recent runs:

```json
{
  "type": "circleci",
  "parameters": {
    "resource": "pipeline",
    "operation": "getAll",
    "vcs": "github",
    "projectSlug": "myorg/myrepo",
    "returnAll": false,
    "limit": 10
  }
}
```

Monitor a single development stream:

```json
{
  "type": "circleci",
  "parameters": {
    "resource": "pipeline",
    "operation": "getAll",
    "vcs": "github",
    "projectSlug": "myorg/myrepo",
    "returnAll": false,
    "limit": 50,
    "filters": {
      "branch": "main"
    }
  }
}
```

Trigger a release pipeline as part of an automated deploy:

```json
{
  "type": "circleci",
  "parameters": {
    "resource": "pipeline",
    "operation": "trigger",
    "vcs": "github",
    "projectSlug": "myorg/myrepo",
    "additionalFields": {
      "branch": "release/v1.0"
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Use CircleCI to get, list, or trigger CI/CD pipelines for GitHub or Bitbucket projects via the CircleCI API v2.

### Behavior notes

- **Project Slug is `org-name/repo-name`**, not a URL — the slash is encoded for you before the request goes out.
- **Branch and tag are mutually exclusive** when triggering. Set one of them, not both.
- **`Return All` pages through every result** using CircleCI's page tokens; the Limit field is only consulted when Return All is off.
- **`getAll` replaces the item JSON.** If a downstream node needs a field that arrived with the input item, capture it before this node or re-attach it afterwards — pipeline objects overwrite the item wholesale.
- **Triggering only starts the run.** The response describes the newly created pipeline; poll with `get` if you need its final state.