API referenceConsole
ci cd
Polylane will read your CircleCI pipelines, job logs and test results, find why a build failed or a test is flaky, and line it up with recent commits.

Connect

Connect CircleCI from the terminal. Pass --help for the flags CircleCI accepts.

Terminal
polylane integration connect --type circleci

How it works

Projects in the context graph

Polylane maps your CircleCI projects into the context graph. It syncs the organization every hour, and a first time one minute after connect. Each project becomes a circleci.project node, and Polylane deletes the node of a project that the organization no longer lists. For each project that the owner of the token follows, Polylane also stores the project slug and the default branch.

What Polylane monitors

Polylane watches workflow failure rates and durations on each project's default branch:

  • Failure rate: failed and error runs over all finished runs. Cancelled and unauthorized runs do not count.
  • p95 duration: of finished runs.

Polylane reads at most 1,000 runs for each workflow. Only a project that the owner of the token follows, and that has a default branch, gets monitors. A sustained change opens an issue on the project node. CircleCI has no organization-level checks.

Failed builds

CircleCI sends no events to Polylane. Polylane reads CircleCI through its API when it needs data. When GitHub is connected and CircleCI reports its results to GitHub as checks, a failed check suite on the default branch or its merge queue becomes an alert. Polylane triages the alert like any other alert, and a new failure starts an investigation.

Agent tools and changes

Read CircleCI pipelines, step logs, and test results, and request API changes through Polylane. Pipeline status reads are always fresh, so a rerun or a cancel shows on the next call.

Through circleciApi, a GET is a read. Every other method needs a reason, safety review and approval before it runs. Project, insights and organization routes must name the connected organization.

Polylane checks the token every six hours. The check passes only while CircleCI accepts the token and the token still reaches the connected organization.

CircleCI APIs

CircleCI personal API tokens have no scopes. A token can do what its owner can do in CircleCI. Polylane uses these CircleCI APIs:

ToolCircleCI APIWhat it unlocks
circleciPipelinesAPI v2 pipelines, workflows, and jobsFinds the latest pipelines of a project and the failed jobs of a workflow.
circleciJobLogsJob details and step outputReads the output of the failed steps of a job.
circleciTestsAPI v2 test metadata and flaky test insightsReads the failed tests of a job and the flaky tests of a project.
circleciApiAny API v2 endpointCalls the CircleCI API. Calls that change state, such as a rerun or a cancel, need safety review and approval. Environment variables, contexts, and checkout keys are not available, for reads or for changes.

Token replacement

You can replace the personal API token on the CircleCI integration page. The new token must reach the same organization. If it does not, Polylane keeps the current token.

Disconnecting

When you disconnect, Polylane stops the syncs and removes the project nodes of the organization from the context graph. Polylane leaves the personal API token in CircleCI. Remove it under User Settings → Personal API Tokens in CircleCI.

Disconnect

Disconnecting stops every sync and check and deletes the credentials Polylane held. Polylane removes what CircleCI's API lets it remove. The following stays until you remove it yourself:

  • CircleCI personal API token
Terminal
polylane integration disconnect <id>

Tools

4

Operations agents can perform in threads.

Pipelines
List CircleCI pipelines of a project and read the workflows and jobs of one pipeline
Job Logs
Read the step logs of one CircleCI job, failed steps first
Tests
Read the test results of a CircleCI job and list the flaky tests of a project
Api
Call any CircleCI API v2 endpoint with the connected organization token