Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to CircleCI

Scalekit connector
Open markdown

The CircleCI connector lets your AI agent act in each user's CircleCI account. Each user connects their own CircleCI API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 30 tools.

Tools
30
What they doRead · write · destructive
25 · 5 · 025 read5 write0 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the CircleCI connection

    In AgentKit > Connections, create a CircleCI connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'circleci'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize CircleCI:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'circleci_collaborations_list',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their CircleCI credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • circleci_collaborations_listList the organizations the connected user is a member of or collaborates on.Read-only

    List Collaborations

    List the organizations the connected user is a member of or collaborates on. Returns each organization's id, name, slug (for example gh/acme), vcs_type and avatar_url. Use this first to find the org slug or organization id that the pipeline, context and insights tools need.

    Inputs

    This tool takes no inputs.

  • circleci_context_envvars_listList the environment variables stored in a CircleCI context, without their values.Read-only

    List Context Environment Variables

    List the environment variables stored in a CircleCI context, without their values. Returns each variable's variable (name), context_id, created_at and updated_at, plus next_page_token. Secret values are never returned. Use this to check which variables a context provides to jobs.

    Inputs

    context_idstringrequired
    UUID of the context, from the id field returned by circleci_contexts_list. Example: 0d4fbe39-e6a0-4b5b-9a8f-3d1a4f1c2e77
    page_tokenstring
    Pagination token from the next_page_token field of the previous response. Leave empty for the first page. Example: AARLwwV5WgM1TjFGmBJuDWeBbZt7
  • circleci_context_getGet a CircleCI context by its UUID.Read-only

    Get Context

    Get a CircleCI context by its UUID. Returns the context's id, name and created_at. Use this to check a context's name. Use circleci_context_envvars_list to see which variables it holds.

    Inputs

    context_idstringrequired
    UUID of the context, from the id field returned by circleci_contexts_list. Example: 0d4fbe39-e6a0-4b5b-9a8f-3d1a4f1c2e77
  • circleci_contexts_listList the contexts (shared sets of environment variables) that belong to a CircleCI organization.Read-only

    List Contexts

    List the contexts (shared sets of environment variables) that belong to a CircleCI organization. Returns each context's id, name and created_at, plus next_page_token. Use this to find a context id for circleci_context_get or circleci_context_envvars_list. Provide owner_id or owner_slug.

    Inputs

    owner_idstring
    UUID of the organization that owns the contexts, from the id field of circleci_collaborations_list or Organization Settings > Overview. Provide this or owner_slug. Example: c9a2d8e4-5f1b-4a7c-8e3d-2b6f9a0c1d4e
    owner_slugstring
    Organization slug, for example gh/acme, from the slug field of circleci_collaborations_list. Provide this or owner_id. Example: gh/acme
    owner_typestring
    Type of the owner: organization (the default, for CircleCI cloud) or account (for CircleCI server installations). Example: organizationone of organizationaccount
    page_tokenstring
    Pagination token from the next_page_token field of the previous response. Leave empty for the first page. Example: AARLwwV5WgM1TjFGmBJuDWeBbZt7
  • circleci_insights_flaky_tests_listList the flaky tests CircleCI detected in a project, across all branches.Read-only

    List Flaky Tests

    List the flaky tests CircleCI detected in a project, across all branches. A flaky test passed and failed on the same commit. Returns flaky_tests with test_name, classname, file, job_name, workflow_name, times_flaked, pipeline_number and time_wasted, plus total_flaky_tests. Use this to find unreliable tests. Use circleci_job_tests_list for the results of one job.

    Inputs

    project_slugstringrequired
    Project slug in the form vcs-slug/org-name/repo-name, copied from Project Settings > Overview in CircleCI. GitHub OAuth projects use gh/<org>/<repo> and Bitbucket projects bb/<org>/<repo>; GitHub App and GitLab projects use circleci/<organization-id>/<project-id>. Example: gh/acme/web-app
  • circleci_insights_org_summary_getGet summary metrics with trends for a whole CircleCI organization and for each of its projects.Read-only

    Get Organization Insights Summary

    Get summary metrics with trends for a whole CircleCI organization and for each of its projects. Returns org_data (metrics and trends for total_runs, total_duration_secs, total_credits_used, success_rate, throughput), org_project_data per project, and all_projects. Use this for an organization-wide health overview. Use circleci_insights_workflows_list to drill into one project.

    Inputs

    org_slugstringrequired
    Organization slug in the form vcs-slug/org-name, from the slug field of circleci_collaborations_list. Example: gh/acme
    reporting_windowstring
    Time window used to calculate the summary metrics. CircleCI uses last-90-days when omitted. One of last-24-hours, last-7-days, last-30-days, last-60-days, last-90-days. Example: last-30-daysone of last-24-hourslast-7-dayslast-30-dayslast-60-dayslast-90-days
  • circleci_insights_test_metrics_getGet test metrics for one workflow of a CircleCI project, calculated from its 10 most recent runs.Read-only

    Get Workflow Test Metrics

    Get test metrics for one workflow of a CircleCI project, calculated from its 10 most recent runs. Returns average_test_count, total_test_runs, most_failed_tests, slowest_tests (with failed_runs, p95_duration, flaky flag) and test_runs. Use this to find the most failed and slowest tests in a workflow. Use circleci_insights_flaky_tests_list for flaky tests across the project.

    Inputs

    project_slugstringrequired
    Project slug in the form vcs-slug/org-name/repo-name, copied from Project Settings > Overview in CircleCI. GitHub OAuth projects use gh/<org>/<repo> and Bitbucket projects bb/<org>/<repo>; GitHub App and GitLab projects use circleci/<organization-id>/<project-id>. Example: gh/acme/web-app
    workflow_namestringrequired
    Name of the workflow as defined in the project's .circleci/config.yml, for example build-and-test. Use circleci_insights_workflows_list to see the names that have run. Example: build-and-test
    all_branchesboolean
    Set to true to aggregate data across all branches instead of a single branch. Use either this or branch, not both. Example: true
    branchstring
    Name of a VCS branch to limit results to. Defaults to the project's default branch. Do not combine with all_branches. Example: main
  • circleci_insights_workflow_jobs_listGet summary metrics for each job of one workflow in a CircleCI project over a reporting window.Read-only

    List Workflow Job Insights

    Get summary metrics for each job of one workflow in a CircleCI project over a reporting window. Returns per job: name, metrics (total_runs, successful_runs, failed_runs, success_rate, throughput, total_credits_used, duration_metrics) and window_start/window_end, plus next_page_token. Metrics cover up to 90 days, are refreshed daily and may miss the last 24 hours; they are not a billing source. Use this to find the slowest or least reliable jobs in a workflow.

    Inputs

    project_slugstringrequired
    Project slug in the form vcs-slug/org-name/repo-name, copied from Project Settings > Overview in CircleCI. GitHub OAuth projects use gh/<org>/<repo> and Bitbucket projects bb/<org>/<repo>; GitHub App and GitLab projects use circleci/<organization-id>/<project-id>. Example: gh/acme/web-app
    workflow_namestringrequired
    Name of the workflow as defined in the project's .circleci/config.yml, for example build-and-test. Use circleci_insights_workflows_list to see the names that have run. Example: build-and-test
    all_branchesboolean
    Set to true to aggregate data across all branches instead of a single branch. Use either this or branch, not both. Example: true
    branchstring
    Name of a VCS branch to limit results to. Defaults to the project's default branch. Do not combine with all_branches. Example: main
    job_namestring
    Full job name, or a substring of it, to limit the results to matching jobs. Leave empty for every job. Example: test
    page_tokenstring
    Pagination token from the next_page_token field of the previous response. Leave empty for the first page. Example: AARLwwV5WgM1TjFGmBJuDWeBbZt7
    reporting_windowstring
    Time window used to calculate the summary metrics. CircleCI uses last-90-days when omitted. One of last-24-hours, last-7-days, last-30-days, last-60-days, last-90-days. Example: last-30-daysone of last-24-hourslast-7-dayslast-30-dayslast-60-dayslast-90-days