CircleCI NewsLast Updated Nov 16, 202614 min read

CircleCI onboarding toolkit: User-friendly tools to help you ship sooner

Jacob Schmitt

Principal Content Producer

Adopting CI/CD tooling is one of the best investments your organization can make to shorten delivery cycles and keep infrastructure costs in check. Before CircleCI can run your pipeline for the first time, someone has to connect a repository, choose a CircleCI organization, and write a config that tells CircleCI what to run. With the CircleCI CLI, that someone can be your coding agent.

circleci onboard, the first tool in the CircleCI onboarding toolkit, handles that setup from your repo: sign-up, the CircleCI organization, the project, the GitHub connection through the CircleCI GitHub App, a starter config if you need one, and a trigger so pushes start runs. Coding agents and developers use the same CLI, so you can hand the whole job to your agent in one sentence, or run each step yourself.

This tutorial starts with the agent, then walks through what onboard does step by step, how to check and troubleshoot the setup, and how to build on your first run with the rest of the toolkit.

Prerequisites

To follow along, you need:

  • A GitHub repository: your own, or a fork of the demo repo described below.
  • A CircleCI account. If you don’t have one, circleci onboard helps you sign up.
  • The CircleCI CLI, installed on the machine where you and your agent work. With Homebrew:

    brew install circleci
    

You can follow every step with your own repository or with the flask-demo repo, a small Flask app with one pytest test and no CircleCI config. To use the demo, fork it on GitHub, then clone your fork and move into it:

git clone https://github.com/<your-github-username>/flask-demo.git
cd flask-demo

Use your fork rather than the original, because onboard connects the repository your clone points to, and you need to be able to install the CircleCI GitHub App on it. The example output in this tutorial comes from the demo repo; with your own repo, the details will differ.

For Linux packages, other platforms, and replacing a legacy 0.1.x CLI, see Getting started with the CircleCI CLI.

Using Bitbucket Cloud or GitLab, or prefer to set up in the browser? Create the project in the web app instead, or follow setting up continuous integration with GitHub for a full walkthrough.

Onboarding with a coding agent

With the CLI installed, open your coding agent, such as Claude Code or Codex, in your repo or your clone of the demo repo, and ask:

Use the CircleCI CLI to set up our project.

From there, the agent does the work. It reads the CLI’s help, finds circleci onboard, and runs it: the command sets up your CircleCI organization and project, writes a config, and connects the repo. Two steps happen in your browser, so the agent hands them to you: signing in to CircleCI (choose Admin when the CLI asks for an access level) and installing the CircleCI GitHub App on the repo.

When setup finishes, review the config the agent wrote, then let it push and watch the first run.

Onboarding a repository with circleci onboard

If you’d rather run onboard yourself, or want to see what your agent is doing, here’s each step. circleci onboard runs each setup step in the terminal and opens the browser when it needs you; the CLI onboarding docs cover the same flow.

Generating and validating a config

Every CircleCI project runs from a config file, .circleci/config.yml, that defines the jobs to run and the order to run them in. You can let onboard write a minimal starter config, or generate one that matches your project’s language and test command first. A generated config gives your first run real work to do: installing dependencies and running your tests. Validating it before you push catches mistakes like a misspelled key before they cost you a run.

Which path fits depends on your tests. Does your test command, such as npm test or pytest, pass locally?

  • No tests yet: skip ahead to running onboard (this includes npm’s default test script, which always fails). The command writes a minimal starter config with one placeholder step that passes. When you add tests, delete the starter config and run circleci config generate, which never overwrites an existing config.
  • Tests fail: fix them first, or skip ahead and use the starter config.
  • Tests pass: generate a config from your project.

To detect your stack and write .circleci/config.yml, run:

circleci config generate

On the demo repo, it prints ✓ Detected python project (cimg/python:3.15.2) and writes the config below. With your own repo, the image tag and commands may differ.

# Generated by circleci config generate
version: "2.1"
jobs:
  build:
    docker:
      - image: cimg/python:3.15.2
    steps:
      - checkout
      - run:
          name: install
          command: pip install -r requirements.txt
      - run:
          name: test
          command: pytest
workflows:
  build:
    jobs:
      - build

The config defines a build job that checks out the code, installs dependencies, and runs pytest in a cimg/python image, plus a workflow that runs it. To learn what each key does, see the introduction to YAML configurations, the configuration introduction, and the configuration reference.

Before you push, check the config:

circleci config validate

If the config is valid, it prints:

Config file at ".circleci/config.yml" is valid.

In a terminal, circleci config generate detects a Python project and writes .circleci/config.yml, and circleci config validate reports that the config file is valid.

validate checks the config’s structure, not whether your commands succeed: it catches a misspelled key before a push starts a run, but a failing test still fails the run.

Running circleci onboard

Run onboard from the repo root:

circleci onboard

When it asks what you’d like to do, choose Set up this repo on CircleCI, even if you don’t have a CircleCI account yet.

In a terminal, circleci onboard asks what you would like to do, with Set up this repo on CircleCI selected above Sign up for CircleCI.

The command then lists every setup step and the directory it runs in. Press Enter to continue.

The circleci onboard preamble lists its setup steps, from generating a starter config to setting up the first pipeline trigger, and the directory it will run in.

It skips steps that are already done, so it uses the config you generated, or writes the starter config if you didn’t generate one.

Next, it signs you in. When it asks where you use CircleCI, choose circleci.com. When it asks how to authenticate, choose Login with a web browser, then press Enter to open the browser. From here, you have about 5 minutes to finish in the browser.

In the browser, select Sign up and use your email address.

The CircleCI sign-up page that circleci onboard opens has a Sign up button, the commands to install the CLI and run circleci onboard, and a link to sign up with Bitbucket Cloud.

Set a password and verify your email from the link CircleCI sends. Then set up MFA with your authenticator app and save the recovery code.

On the Authorize CircleCI CLI? page, choose Admin under Access level and select Allow. The page defaults to Read, and onboard needs Admin access to connect the GitHub App. The terminal then reports that you’re logged in.

With a new account, onboard asks you to name your first CircleCI organization; use your team’s name or your username.

Accept the default project name, which is the repo’s name. The command creates the project, writes .circleci/info.yml to record which project this checkout belongs to, and follows the project. It also prints a Pipelines link to the project in the web app.

The browser then opens the CircleCI GitHub App install page. Choose the GitHub account or organization that owns the repo, select Only select repositories, add this repo, and select Install & Authorize. GitHub may ask for your two-factor authentication (2FA) code, so have it ready: the command waits up to 3 minutes for the install. If it times out, finish the install and rerun onboard, which picks up where it left off. It skips this step if your CircleCI organization already has the App.

The GitHub page to install and authorize the CircleCI GitHub App on the rw-onboard-demo organization, with Only select repositories chosen and only the flask-demo repository selected.

Once the App is installed, onboard creates the project’s pipeline (the output calls it a pipeline definition), adds a trigger for all pushes, and ends with output like this:

✓ Pipeline definition created: flask-demo
✓ Trigger created: all-pushes

Your project is ready! Next steps:
  1. git add .circleci/
  2. git commit -m "Add CircleCI config"
  3. git push

Pushing will trigger your first pipeline.

The exact wording can vary between CLI releases.

Pushing and watching the first run

Commit the config, push it, and watch the run:

git add .circleci/
git commit -m "Add CircleCI config"
git push
circleci run watch --sha "$(git rev-parse HEAD)"

Each push starts a run of your project’s pipeline; the web app lists runs under Pipelines. run watch follows the run for the commit you pushed until it finishes. It exits 0 when the run passes, and non-zero when the run fails or when no run appears within 2 minutes. If the run fails, see the troubleshooting table below.

In a terminal, the config is committed and pushed, and circleci run watch follows the run until the build job and the run succeed.

To see the run in the web app, open the Pipelines link that onboard printed, or open the latest run on the current branch:

circleci run open

The CircleCI web app's Pipelines page for the flask-demo project shows the run from the Add CircleCI config commit on main, with the build workflow marked Success.

Checking what was set up

In a CircleCI organization like the one you created:

  • Commit .circleci/info.yml with the config (git add .circleci/ covers it) so your teammates’ and agents’ CLIs know which project the checkout belongs to.
  • The all-pushes trigger starts a run for every push with new commits, to any branch. To narrow it, edit the trigger in the project’s settings in the web app. Tags run workflows only if your config adds tag filters.
  • The CLI can’t delete projects, but the web app can.

If your existing CircleCI organization’s slug starts with gh/ or bb/ (it connects through GitHub OAuth or Bitbucket), onboard prints that the project is connected and tells you to commit and push. There’s no info.yml or trigger to manage.

If you joined a team and the repo has no .circleci/info.yml yet, run onboard and choose the team’s CircleCI organization.

Troubleshooting your setup and first run

Most setup problems show up as a ⚠ warning in onboard’s output, or as a push that doesn’t start a run. Whether you or your agent ran onboard, find the message you saw in the table below. After a fix, rerun circleci onboard: it skips the steps that are already done and picks up where it stopped.

Symptom Fix
circleci onboard prints “No git repository found” Run it from the repo root.
Authorize CircleCI CLI? shows the wrong account under Logged in as Select Deny, sign out of circleci.com, and rerun onboard.
⚠ Could not check the GitHub App installation: … 404 Not Found The CLI lacks Admin access. Run circleci auth logout and circleci auth login, choose Admin, and rerun onboard.
Sign-in timed out (onboard waits 5 minutes for the browser) Run circleci auth login if you finished creating the account, then rerun onboard.
⚠ Timed out waiting for the GitHub App installation. Finish the install, ignore the printed pipeline create and project trigger create hint, and rerun onboard.
⚠ Could not list GitHub App repositories: … 401 Unauthorized Usually your GitHub account is linked to a different CircleCI account, and the web app shows “Your GitHub identity is not authorized”. Rerun circleci onboard --repo-id <id> with the repo’s GitHub ID from gh api repos/<owner>/<repo> --jq .id.
The App can’t access the repo Add the repo on the CircleCI App’s Configure page in your GitHub settings, or install the App on the account that owns the repo, then rerun onboard.
You can’t install the App because you’re not an owner or admin Run circleci onboard --no-browser and send the printed GitHub App install link to a GitHub organization owner. After they install it, rerun onboard.
The remote uses an SSH host alias or contains credentials Run git remote set-url origin https://github.com/<owner>/<repo>.
The run failed (run watch exits non-zero after showing the run) Run circleci run get --failure-report to see every failed step.
run watch prints error: No run found for commit <sha> … after 2m0s. Check that onboard printed a “Trigger” line or “Project connected”, and that you pushed a new commit that includes .circleci/.

Building on your first pipeline

Once your first run passes, the rest of the onboarding toolkit helps you build on it. The same CLI lets you and your agents watch runs, pull failure reports, check test results, and manage settings, and its data commands take --json. To see those commands work through a failed run, read how to debug CircleCI runs from the terminal.

Getting config help in your editor

The CircleCI extension for VS Code, on the Visual Studio Marketplace and on Open VSX for Cursor and Windsurf, includes a Config Helper for .circleci/config.yml. It adds validation, syntax highlighting, go-to-definition and go-to-reference, hover documentation, autocomplete, and usage warnings. Errors and warnings appear in the Problems panel, and the Config Helper works without signing in to CircleCI. To validate on demand, run CircleCI: Validate current configuration file from the Command Palette.

In VS Code, a config.yml with the key command misspelled as comand is open, and the Problems panel lists the Config Helper error "command is required" and a warning that asks "Did you mean command?"

In JetBrains IDEs, install the CircleCI plugin from the JetBrains Marketplace.

Your coding agent can get the same help. The Config Helper runs on CircleCI’s open-source YAML language server, so the diagnostics and hover documentation you see in VS Code can also reach an agent while it edits .circleci/config.yml. Read our guide How to build a Language Server Protocol (LSP) plugin for Claude Code to learn how to give those same capabilities to Claude Code or other coding agents. In that guide’s benchmark, the language server’s guidance led Claude to add store_test_results and keep orbs on current versions.

Speeding up the pipeline

Dependency caching saves installed packages between runs. For the generated Python config, replace the steps of the build job with this version, which caches the install and stores the test results:

steps:
  - checkout
  - restore_cache:
      keys:
        - pip-v1-{{ checksum "requirements.txt" }}
  - run:
      name: install
      command: pip install -r requirements.txt
  - save_cache:
      key: pip-v1-{{ checksum "requirements.txt" }}
      paths:
        - ~/.cache/pip
  - run:
      name: test
      command: pytest --junitxml=test-results/junit.xml
  - store_test_results:
      path: test-results

store_test_results adds per-test results to the job at no cost, and Smarter Testing builds on those results. Static test splitting, rerun from failed (which reruns only the failed tests), and test uploads are free. Test impact analysis, dynamic test splitting, dynamic parallelism, and auto rerun count against a monthly test-atom allowance on every plan, with a credit charge above it. The Smarter Testing tutorial sets it up on a sample app.

To right-size a job, check its Resources tab, which shows how much of its resource class it used; the resource class overview lists the sizes you can choose. Parallelism runs a job across several containers, and test splitting divides the tests among them. If you build Docker images, Docker layer caching reuses unchanged layers between runs. Self-hosted runners run jobs on your own machines. Insights in the web app tracks each workflow’s duration, success rate, throughput, and credit use.

Adding secrets and deploying safely

Store secrets as project environment variables. Run this yourself, not through an agent:

circleci envvar set NAME "$(cat secret.txt)"

Contexts share secrets across projects, and OpenID Connect (OIDC) tokens let jobs authenticate to cloud providers without stored keys. To ship, add a deploy job from an orb or write your own; the deployment overview covers the options. circleci deploy init adds deploy markers to your config, so each release appears on the Deploys page. Once you set up a rollback pipeline (it needs a GitHub repo, the GitHub App, and deploy markers), circleci deploy rollback runs it, and Smart Deployments runs it automatically when monitoring flags a failed release. For a worked example, see how to set up rolling deployments with CircleCI.

Sharing config across projects

Orbs are reusable packages of config. The Orb Registry is the usual way to add third-party jobs, though partner and community orbs need a CircleCI organization admin to opt in. Private orbs, for internal tooling, are available on all plans.

For larger organizations, config policies on the Scale plan enforce rules across every pipeline once a CircleCI organization admin enables them: a hard_fail violation blocks the pipeline from running, and a soft_fail violation is logged. CircleCI config policies: A tale of empowerment and control explains how security teams use them.

Conclusion

In this tutorial, you installed the CircleCI CLI and either asked your coding agent to set up your project or ran circleci onboard yourself. You generated and validated a config, and onboard created your CircleCI organization and project, connected the repo through the CircleCI GitHub App, and added a trigger so every push starts a run. Then you pushed your config and watched your first run pass.

That first green run is a starting point. From here, keep building: cache dependencies and store test results, let Smarter Testing run only the tests that matter, add a deploy job, and share config across projects with orbs. When you need help along the way, read the CircleCI docs or ask on Discuss.

Sign up for a free CircleCI account, or run circleci onboard in your repo.