Monitoring of CircleCI projects in Pipedash, with pipeline history, trigger parameters, workflow reruns, cancellation and job logs.
The CircleCI plugin (circleci) monitors the latest pipeline of each selected project. It loads pipeline history, starts pipelines, reruns workflows and cancels active workflows. It also shows job logs inside Pipedash.
Requirements
The plugin authenticates with a personal API token created under "User Settings > Personal API Tokens". The token reads and runs pipelines in every project the user can access.
Pipedash sends the token in the Circle-Token header and validates it with GET /api/v2/me. API requests also send Accept: application/json.
HTTP 401 reports an authentication error. HTTP 403 reports permission denied, unless the response identifies an exhausted rate limit. HTTP 429 reports a rate limit. HTTP 5xx reports service unavailable.
Configuration

| Key | Type | Required | Default | Description |
|---|---|---|---|---|
token | Password | Yes | None | CircleCI personal API token, created under User Settings > Personal API Tokens. It reads and runs pipelines in every project the user can access. |
base_url | Text | No | https://circleci.com | Leave as https://circleci.com for CircleCI cloud, or use the address of your CircleCI server. |
insecure | Boolean | No | false | Skip TLS certificate verification (useful for self-signed certificates). |
The dialog labels these fields "Personal API Token", "CircleCI URL" and "Skip TLS Verification".
One more key goes in the config table of the TOML file:
selected_items: Comma-separated project slugs. Each slug has the formgh/org/repofor a GitHub project,bb/org/repofor a Bitbucket project orcircleci/org-id/project-idfor a CircleCI App project.
Without selected_items, Pipedash monitors the followed projects that CircleCI returns. An explicitly empty selected_items value monitors no projects. Each slug has exactly three parts. The last two parts accept ASCII letters, numbers, hyphens, _ and periods. Empty parts, . and .. are invalid.
Base URL
base_url defaults to https://circleci.com. Set it to the origin of a CircleCI server for a self-hosted connection. HTTP and HTTPS are accepted.
The URL must have no path other than /, no credentials, no query and no fragment. Pipedash removes surrounding whitespace and trailing slashes. The form reports "Must be an HTTP or HTTPS address without a path" for an invalid format.
CircleCI API routes use /api/v2. Project discovery and job-step reads also use /api/v1.1.
Links to runs use https://app.circleci.com for the default cloud URL. A custom connection uses its configured origin.
Pipeline discovery
The picker lists followed projects from GET /api/v1.1/projects. It does not list individual workflow definitions. GitHub projects use the gh slug prefix and Bitbucket projects use bb.
The organization picker comes from the organizations of those followed projects. Each project shows its repository name, organization and repository, with a description such as Project: gh/acme/web | Default branch: main.
Search matches the project name and project slug, ignoring case. It does not search the description or the default branch.

The app loads picker results in pages of 100. Pipedash fetches the followed-project list before it applies the organization filter, the search and the local pagination.
The followed-project discovery does not produce circleci/org-id/project-id entries. CircleCI App project slugs go in selected_items in the TOML file.
What a row represents
One pipeline row represents one CircleCI project. One history row represents one CircleCI pipeline execution. A run combines the latest attempt of each workflow name in that execution.
Pipedash picks the workflow attempt with the latest created_at value. The log tree lists those workflow names alphabetically.
A project with no pipeline yet shows pending. Its branch falls back to the default branch of the project.
A failure while reading a selected project, its latest pipeline or its workflows fails the refresh. Pipedash does not skip that project and return a partial list.
The pipeline table has Name, Status, Repository and Branch columns. A sortable "Project Slug" column is hidden by default.
Run history
The latest-run refresh asks for the first pipeline that GET /api/v2/project/{slug}/pipeline returns.
History uses the same endpoint. Pipedash follows next_page_token through the page-token query parameter until it has the requested number of pipelines or CircleCI returns no next token. Workflow and job lists follow all available pages. A repeated pagination token fails with CircleCI repeated a pagination token.
Pipedash sets no upstream page size and adds no fixed history limit. The history view shows 20 runs per page, ordered by run number, newest first, by default. The shared history loader widens its request in steps as the view needs older runs.
The history table has Run, Status, Branch, Started and Duration columns. Commit and Actor are hidden by default. Branch, Commit and Actor depend on the data that CircleCI supplies.
The run number is the CircleCI pipeline number. Workflow IDs and job numbers identify parts of that pipeline. The internal run ID is {project-slug}__{pipeline-uuid}.
Run details load with GET /api/v2/project/{slug}/pipeline/{number}. Pipedash reads the workflows with GET /api/v2/pipeline/{pipeline-id}/workflow.
The start time is the earliest start time of the latest workflow attempts. A workflow without started_at uses created_at. Without either, the run uses the creation time of the pipeline. A finished run ends at the latest workflow stop time, or at the update time of the pipeline when no workflow supplies one. Running and pending runs have no end time.
The details include the branch, commit revision, commit subject and trigger actor when CircleCI supplies them. Pipedash does not store trigger inputs for these runs.
Trigger parameters
Pipedash reads pipeline parameters from the source config of the latest pipeline, with GET /api/v2/pipeline/{pipeline-id}/config. It keeps their declaration order.
A project without a previous pipeline or without a config source has no discovered pipeline parameters. A YAML parse failure leaves the Branch field available but omits the parameters of the config. A failed API request fails parameter loading.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
branch | String | Yes | Default branch of the project, when supplied | The "Branch" field. Branch to build. |
pipeline | Choice | Yes, when shown | First pipeline definition returned | The "Pipeline" field. Shown for a CircleCI App project with more than one pipeline definition. |
parameters.<name> | String, Boolean, Number or Choice | Yes, when the declaration has no default | Declared default | A top-level pipeline parameter from the CircleCI config. |
CircleCI string, boolean, integer and enum declarations become String, Boolean, Number and Choice fields. Other types do not appear. Parameter labels use their declared names, and descriptions come from the config. A Boolean without a usable default starts as false. Enum choices come from the enum list of the declaration.
Pipedash removes the parameters. prefix before it sends the API request. A cleared optional string is sent as "", even when the declaration has a non-empty default. An absent parameter or a null value is omitted. An explicit false or 0 is kept.
Required fields reject an empty or whitespace-only string with <label> is required.

GitHub and Bitbucket projects
For a gh/... or bb/... project, Pipedash sends POST /api/v2/project/{slug}/pipeline:
{
"branch": "main",
"parameters": {
"deploy": true,
"count": 3,
"message": ""
}
}The parameters object is omitted when it has no entries.
CircleCI App projects
For a circleci/... project, Pipedash loads the definitions with GET /api/v2/projects/{project-id}/pipeline-definitions.
A project with one definition uses it automatically. With several definitions, the "Pipeline" field selects one by name. API inputs can select a definition by its name or its ID.
Pipedash sends POST /api/v2/project/{slug}/pipeline/run. The chosen definition supplies definition_id. Both config.branch and checkout.branch use the selected branch:
{
"definition_id": "definition-id",
"config": {
"branch": "develop"
},
"checkout": {
"branch": "develop"
}
}The request adds parameters when pipeline parameters are supplied.
A successful trigger returns the new pipeline number. It does not return an internal Pipedash run ID.
Rerun and cancel
A rerun stays under the same pipeline number. Pipedash acts on the latest attempt of each workflow name.
"Rerun" sends POST /api/v2/workflow/{workflow-id}/rerun with {"from_failed": false} for each eligible latest workflow.
"Rerun failed jobs" sends the same request with {"from_failed": true}. It selects only eligible workflows whose state is failed or error.
After a pipeline continues beyond setup, both actions skip workflows tagged setup. They rerun the continued workflows without restarting setup. When every latest workflow is tagged setup, both actions can rerun setup instead.
Pipedash refuses both rerun actions while any latest workflow is running, failing, on_hold, pending or queued.
Cancel sends POST /api/v2/workflow/{workflow-id}/cancel for each latest workflow in one of those active states. Finished workflow attempts are not cancelled.
Pipedash does not approve CircleCI approval jobs. Those jobs can appear in the log tree, but have no log content. They are approved in CircleCI.
Run logs
The Logs tab groups jobs under the latest attempt of each workflow. Workflow groups have no log content of their own. A numbered job can have a log. Approval jobs and skipped jobs have no log.
A running job has a partial log. A pending job waits for logs. A finished job has a log only when CircleCI supplies its start time.
Pipedash loads jobs with GET /api/v2/workflow/{workflow-id}/job. It reads the steps of a job from GET /api/v1.1/project/{vcs}/{organization}/{project}/{job-number}. The VCS path is github, bitbucket or circleci, according to the project slug.
Each step action can supply an output_url. Pipedash downloads that URL without the Circle-Token header. The URL must use HTTPS or share the configured CircleCI origin. URLs with credentials are rejected.

Step sections
Each step action becomes a section. Parallel actions have names such as Run tests (container 0).
Failed actions start open. This applies when failed is true or the action status is failed, timedout, infrastructure_fail or canceled. Other sections start closed.
The plugin generates timestamped log markers. # starts a closed section, + starts an open section and . marks an output line. A timestamp follows the marker, or - when no timestamp exists. Output timestamps come from the CircleCI messages. Step timestamps come from the start time of the action.
The viewer also identifies errors from the output text.
Live updates and resume
Pipedash reads the log of a running job about every 2 seconds while the log is open. It reads the steps and output URLs again, because CircleCI offers no provider-side log stream. The workflow and job tree refreshes about every 5 seconds.
Pipedash renders the job log before it checks the resume cursor. If the previous rendered text remains an unchanged prefix, it appends only the new suffix. If the text changes or gets shorter, it replaces the log.
Output limits
One step action output is limited to 32 MiB of downloaded JSON. A larger response is omitted instead of shown as a truncated JSON document.
The job output budget is 128 MiB of decoded message text. An action that exceeds the remaining budget and every later action are omitted.
An omitted action shows "This step printed more output than Pipedash loads. Open the job in CircleCI to see it."
Missing logs and errors
An HTTP 404 while reading a log shows "The provider no longer has this log. It may have expired."
An HTTP 410 from a step-output request is not treated the same way. It reports CircleCI step output returned HTTP 410 as an API error.
Invalid output JSON reports Invalid CircleCI step output. An invalid output address reports CircleCI sent an invalid step output URL.
The Run logs page covers the viewer.
Status page
The CircleCI plugin has no built-in status page, no status_page_url field and no component-health checks. It does not read the public status page of CircleCI.
Errors
| Error text | Meaning |
|---|---|
Missing token in config | No non-empty token. |
Invalid CircleCI token header | The token cannot become an HTTP header. |
Use a CircleCI project slug: gh/org/repo, bb/org/repo or circleci/org-id/project-id | A configured project slug is invalid. |
CircleCI base URL must be an HTTP or HTTPS origin without credentials | The URL has credentials, a query, a fragment or a path other than /. |
Unknown CircleCI VCS host or Unknown CircleCI VCS type | A followed project cannot become a supported slug. |
Choose a branch to build | The trigger has no non-empty branch and the project has no default branch. |
CircleCI has no pipeline named <chosen> | No definition matches the supplied name or ID. |
This CircleCI project has no pipelines to run | The App project has no pipeline definitions. |
Choose which CircleCI pipeline to run | The App project has several definitions and no choice. |
CircleCI did not return an id for project <slug> | The definition lookup of an App project lacks the project ID. |
CircleCI did not start a pipeline: <message> | The trigger response has no positive pipeline number and supplies a message. |
CircleCI trigger response has no pipeline number | The trigger response has neither a positive pipeline number nor a message. |
Pipeline #<number> has no running workflows to cancel | No latest workflow is active. |
Pipeline #<number> is still running. Wait for it to finish or cancel it | A rerun was requested while a latest workflow is active. |
Pipeline #<number> has no workflows to rerun or Pipeline #<number> has no failed workflows to rerun | No latest workflow matches the rerun action. |
TOML example
[providers.circleci-work]
name = "CircleCI Work"
type = "circleci"
token = "${CIRCLECI_TOKEN}"
refresh_interval = 30
[providers.circleci-work.config]
base_url = "https://circleci.com"
insecure = "false"
selected_items = "gh/acme/web,bb/acme/mobile"A CircleCI App project uses its slug in selected_items, for example circleci/org-id/project-id.
Status mapping
Pipedash first applies pipeline-level rules:
| Pipedash status | CircleCI pipeline condition |
|---|---|
failed | State is errored, or the pipeline has any errors |
running | State is setup, unless the failure rule applies |
pending | State is pending or setup-pending, or no workflows exist, unless an earlier rule applies |
| Aggregated workflow status | Any other case, using the latest attempt of each workflow name |
Workflow states map as follows:
| Pipedash status | CircleCI workflow state |
|---|---|
success | success |
failed | failed, error, unauthorized |
running | running, failing |
pending | Any other state, including on_hold, pending and queued |
cancelled | canceled |
skipped | not_run |
When workflows differ, the aggregate takes the first status in this priority order: running, pending, failed, cancelled, success, skipped.
Jobs in the log tree have a separate mapping:
| Pipedash status | CircleCI job state |
|---|---|
success | success |
failed | failed, infrastructure_fail, timedout, terminated-unknown, unauthorized |
running | running |
pending | Any other state |
cancelled | canceled |
skipped | not_run, retried |