CircleCI integration

What it does

The CircleCI integration lets you wire continuous-delivery automations on behalf of any client whose CircleCI account you operate. Connect a CircleCI account once with a Personal API Token, then trigger pipelines on demand, list recent runs, cancel a flaky workflow, and route live workflow- and job-completed events into the rest of your workflow without writing any custom CI tooling.

Connect a CircleCI account

1. In TaskJuice, open Settings -> Connections and choose Add connection -> CircleCI.
2. In CircleCI, click your avatar in the lower-left, open User Settings -> Personal API Tokens, and choose Create New Token. Give the token a descriptive name (for example, taskjuice-prod) and copy the value.
3. Paste the token into the Personal API Token field in TaskJuice and save.

The token authorises every CircleCI v2 REST call against api.circleci.com on the owning user's behalf. Rotate or revoke it from the same User Settings -> Personal API Tokens page at any time.

Triggers

• circleci/workflow-completed. Fires when a CircleCI workflow finishes (success, failed, canceled, errored, or unauthorized).
• circleci/job-completed. Fires when a single job within a workflow finishes.

To enable a trigger, open the CircleCI project's Project Settings -> Webhooks page, choose Add Webhook, point it at the TaskJuice incoming webhook URL, paste the recipe signing secret into the Signing Secret field, and tick the matching event. CircleCI signs every request body with HMAC-SHA256 and sends the hex digest in the Circleci-Signature header, prefixed with v1=. TaskJuice verifies that signature on every inbound POST.

Actions

• circleci/get-current-user. Returns the authenticated CircleCI user. Useful as a connection sanity check.
• circleci/list-project-pipelines. List recent pipelines for a project, filtered by branch or to runs triggered by the connected user. Supports cursor pagination via the page-token parameter.
• circleci/trigger-pipeline. Trigger a new pipeline on a project, optionally pinned to a branch or tag with a parameters map that overrides config inputs declared in .circleci/config.yml.
• circleci/cancel-workflow. Cancel a running workflow by ID. Useful for stopping a flaky build or freeing concurrency when a downstream signal indicates the run is no longer needed.

Known limitations

• Rate limits follow CircleCI's documented per-token ceilings (see CircleCI API rate limits). TaskJuice retries on 429 responses with exponential backoff.
• Cursor pagination follows the v2 next_page_token model. TaskJuice stops paginating after 100 pages by default; raise the ceiling on the action if you need a deeper sweep.
• Personal API Tokens act on behalf of the user that created them and inherit that user's project access. Granting TaskJuice access to a new project requires that user to be added to the project in CircleCI.
• Project slugs use the form {vcs}/{org}/{repo} (for example, gh/acme/api for GitHub or bb/acme/api for Bitbucket). The slug must already be onboarded as a project in CircleCI before any action can target it.
• Webhook signing secrets are configured per-project in CircleCI. A project without a signing secret on its webhook cannot be verified by TaskJuice, and the inbound POST will be rejected.