Getting started with Gemini and CircleCI

AI coding assistants like Gemini are changing how developers write code. They can generate entire functions, debug tricky issues, and help you move faster than ever before. But with that speed comes a new challenge: how do you make sure AI-generated code actually works?

AI assistants are powerful, but they’re not perfect. They can introduce subtle bugs, miss edge cases, or generate code that breaks existing functionality. That’s where CI (continuous integration) comes in. CI automatically runs your tests and checks every time you push code, catching problems before they reach production. When you’re working with AI-generated code, this automated verification is essential.

The good news is that setting up CI takes just a few minutes, and once it’s running, you get an extra layer of confidence every time you accept an AI suggestion.

This tutorial will walk you through the complete setup: getting Gemini as your AI coding assistant, setting up CircleCI as your safety net, and then connecting the two so you can validate configs, trigger pipelines, diagnose failures, and analyze test results. All without leaving your development environment.

Prerequisites

Before we dive in, make sure you have the following ready:

• A CircleCI account (free tier works great)
• A GitHub account
• Node.js 20 or newer installed on your machine
• Either Gemini CLI or Gemini Code Assist for VS Code installed (we’ll cover both options below)

Choose your Gemini experience

Google offers two ways to work with Gemini that both support MCP integrations: Gemini CLI for terminal-first developers, and Gemini Code Assist for those who prefer staying inside VS Code. The good news is that both tools read from the same configuration file, so the CircleCI MCP setup you’ll do in this tutorial works for either one, or both, if you like to switch between them.

Option A: Gemini CLI (terminal)

If you haven’t used Gemini CLI before, it’s an open-source AI agent from Google that brings the power of Gemini models directly into your terminal. It’s designed for developers who prefer working from the command line and want a lightweight, terminal-first experience without the overhead of a full editor.

What makes it particularly useful is its support for MCP (Model Context Protocol), which lets you extend its capabilities with custom tools and integrations. It can read and edit files, execute shell commands, search the web for real-time information, and—as we’ll see in this tutorial—interact with external services like CircleCI.

If you haven’t installed it yet, you can get it with npm:

npm install -g @google/gemini-cli

Or if you’re on macOS and prefer Homebrew:

brew install gemini-cli

Once installed, just run gemini in your terminal to get started. The first time you run it, you’ll authenticate with your Google account, which gives you free access to Gemini 2.5 Pro with a generous 1M token context window—more than enough for even large codebases.

Option B: Gemini Code Assist (VS Code)

If you’d rather work inside an IDE, Gemini Code Assist is Google’s AI-powered extension for VS Code. It offers code completion, chat-based assistance, and—most importantly for this tutorial—an agent mode that supports MCP servers.

Here’s the interesting part: Gemini Code Assist’s agent mode is actually powered by Gemini CLI under the hood. This means it reads from the exact same ~/.gemini/settings.json configuration file, so you only need to set up the CircleCI MCP server once and it works in both environments.

To get started with Gemini Code Assist:

1. Open VS Code and go to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
2. Search for “Gemini Code Assist” and install the extension from Google
3. Sign in with your Google account when prompted
4. Open the Gemini Code Assist chat panel to start using it

Note: MCP server support in Gemini Code Assist requires agent mode, which is available in VS Code. If you’re using IntelliJ or other JetBrains IDEs, MCP servers aren’t currently supported. You’ll want to use Gemini CLI instead.

Why you need CI with your AI coding assistant

AI coding assistants can write code impressively fast, but they don’t have full context about your project’s requirements, existing test coverage, or production constraints. This means AI-generated code should always be verified by automated tests before it ships.

Here’s what can go wrong without CI in the loop:

• Silent breakages: AI might refactor a function in a way that breaks callers elsewhere in your codebase. Without tests running automatically, you won’t know until something fails in production.
• Security oversights: AI models can generate code with vulnerabilities—SQL injection, improper input validation, exposed secrets. CI pipelines with security scanning catch these before they become problems.
• Dependency conflicts: AI suggestions might introduce or update dependencies in ways that conflict with your existing stack. CI ensures your full application still builds and runs.
• Test regressions: Even well-intentioned changes can cause existing tests to fail. CI runs your entire test suite on every push, so you know immediately if something broke.

Think of CI as your automated code reviewer that never sleeps, never gets tired, and checks every single change. When you’re moving fast with AI assistance, that safety net becomes even more valuable.

The workflow is simple: write code with AI help, push your changes, and let CI verify everything works. If something breaks, you find out in minutes instead of days.

Getting started with CircleCI

Setting up CircleCI takes just a few minutes. Here’s the quick version:

1. Sign up: Head to circleci.com and create a free account. You can sign up with your GitHub account for faster setup.
2. Connect your repository: Once logged in, go to the Projects section and find the repository you want to build. Click Set Up Project.
3. Add a config file: CircleCI needs a configuration file at .circleci/config.yml in your repository. If you don’t have one yet, CircleCI can generate a starter config based on your project’s language. Here’s a minimal example:

version: 2.1

jobs:

  build-and-test:

    docker:

      \- image: cimg/node:20.0

    steps:

      \- checkout

      \- run: npm install

      \- run: npm test

workflows:

  main:

    jobs:

      \- build-and-test

1. Trigger your first build: Once the config file is in your repository, CircleCI will automatically run your first pipeline. You can also trigger builds manually from the dashboard.

That’s it. You now have CI running on every push. For more detailed setup instructions, language-specific guides, and advanced configuration options, see the CircleCI Quickstart Guide.

Using the demo repository

If you want to follow along with a project that already has CircleCI configured, you can fork our demonstration repository:

1. Head over to to the demo repo and click the Fork button
2. Sign in to CircleCI and navigate to the Projects section
3. Find your newly forked repository in the list and click Set Up Project
4. Accept the default configuration options and let CircleCI trigger your first pipeline

Once that initial build completes (or fails—either is fine for our purposes), you’ll have some pipeline data to explore with Gemini.

Setting up the CircleCI MCP server

Now for the interesting part. The CircleCI MCP server is what enables Gemini to actually communicate with CircleCI’s APIs, giving it the ability to fetch build logs, trigger pipelines, analyze test results, and more. Setting it up takes just a few minutes, and the same configuration works for both Gemini CLI and Gemini Code Assist.

Step 1: Generate a CircleCI API token

First, you need to create an API token that will authenticate Gemini with CircleCI:

1. Sign in to CircleCI
2. Click your profile avatar in the bottom-left corner of the screen
3. Select User Settings from the menu
4. Navigate to Personal API Tokens in the sidebar
5. Click Create New Token
6. Give it a descriptive name like “Gemini CLI MCP” so you’ll remember what it’s for
7. Click Create Token and immediately copy the value somewhere safe

Note: CircleCI displays this token only once. If you lose it, you’ll need to create a new one. Make sure you save it before moving on.

Step 2: Add the MCP configuration

Both Gemini CLI and Gemini Code Assist look for MCP server configurations in a file called settings.json in your Gemini config directory. Let’s create that now.

On macOS or Linux:

mkdir -p ~/.gemini
nano ~/.gemini/settings.json

On Windows (using PowerShell):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini"
notepad "$env:USERPROFILE\.gemini\settings.json"

Now add the following configuration, making sure to replace your-circleci-token with the actual token you copied in the previous step:

{
  "mcpServers": {
    "circleci": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token"
      }
    }
  }
}

If you’re not comfortable putting your token directly in a config file, you can reference an environment variable instead:

{
  "mcpServers": {
    "circleci": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "$CIRCLECI_TOKEN"
      }
    }
  }
}

Then add the token to your shell profile (like ~/.bashrc or ~/.zshrc):

export CIRCLECI_TOKEN="your-circleci-token"

Step 3: Verify everything is connected

Now make sure the integration is working. The verification process differs slightly depending on whether you’re using Gemini CLI or Gemini Code Assist.

If you’re using Gemini CLI

Open your terminal, navigate to your project directory, and start Gemini CLI:

cd /path/to/your/project
gemini

Once Gemini starts up, check that the MCP server is loaded by typing:

/mcp

circleci should be listed as one of the available servers. If it’s there, you’re all set.

If you’re using Gemini Code Assist in VS Code

After saving your settings.json file, you’ll need to reload VS Code for the changes to take effect:

1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
2. Type “Developer: Reload Window” and press Enter
3. Open the Gemini Code Assist chat panel
4. Switch to agent mode by clicking the agent mode toggle or typing /agent

The CircleCI MCP server should now be available in agent mode.

Verify the connection (both methods):

To really confirm everything is working, try asking Gemini to list your projects:

List my followed projects on CircleCI

Gemini will reach out to CircleCI through the MCP server and display your projects along with their project slugs (which look like gh/your-username/your-repo). If you see your projects listed, congratulations—you’re ready to start using the integration.

Use case 1: Validate your CircleCI config

Start with something simple but incredibly valuable: validating your CircleCI configuration before you push it. There’s nothing worse than pushing a commit only to have the pipeline fail immediately because of a YAML syntax error or a typo in an orb name.

With Gemini connected to CircleCI, you can catch these issues before they waste your time. Just ask:

Validate my CircleCI config

Gemini uses the CircleCI MCP server’s config_helper tool to check your .circleci/config.yml file and returns detailed feedback including whether the config is valid, any specific errors it found (with line numbers), warnings about potential issues, and recommendations for improvements.

This is especially handy when you’re making changes to a complex configuration or experimenting with new orbs and features. You get instant feedback without needing to commit and push just to see if your syntax is correct.

Use case 2: Trigger a pipeline without leaving your editor

Here’s a workflow improvement that might seem small but really adds up: triggering pipeline runs without leaving your development environment. Instead of opening CircleCI in a browser, finding your project, and clicking buttons, just ask:

Run the pipeline for my current branch

Gemini automatically detects your Git remote and current branch, then uses the run_pipeline tool to kick off a build. You’ll get a confirmation message along with a direct link to monitor the pipeline if you want to watch it in the dashboard.

You can also be more specific about what you want to run:

Run the pipeline for the develop branch

Or if you’re working with multiple projects and want to trigger a build on a different one:

Run the pipeline for gh/my-org/my-other-repo on the main branch

The ability to trigger pipelines without context-switching might seem like a minor convenience, but when you’re in the flow of debugging an issue and need to run multiple test iterations, staying in your development environment makes a real difference.

Use case 3: Diagnose failed builds

This is where the integration really pays off. When a build fails, the traditional workflow involves opening CircleCI, navigating to the failed pipeline, expanding the failed job, scrolling through logs to find the error, and then switching back to your editor to fix it. With Gemini, you can shortcut all of that.

Just ask:

Why did my last build fail?

Gemini uses the get_build_failure_logs tool to fetch the relevant information and presents you with a clear explanation of what went wrong. Each job and failed step, is listed, along with the actual command output that shows the error, exit codes and error messages. The display shows enough context from surrounding steps to understand what happened.

But Gemini doesn’t just show you the error—it analyzes the failure and suggests specific fixes. Since you’re already in your development environment with your code available, you can immediately act on those suggestions. Need to update a dependency? Fix a test? Change a configuration value? You can do it right there.

Iterate until the build passes

Here’s where things get really powerful. Instead of manually checking back after each fix, you can ask Gemini to handle the full cycle:

Fix the issue, then run the pipeline and let me know when it passes

Gemini will make the necessary code changes, trigger a new pipeline run, monitor the results, and report back with the outcome. If the build fails again with a different error, you can continue iterating. All without opening a browser or breaking your focus.

Investigate specific pipelines

Sometimes you need to look at a particular pipeline run, maybe one that a teammate mentioned or one from earlier in the day. You can pass a direct link:

Get logs from https://app.circleci.com/pipelines/github/my-org/my-repo/123

Use case 4: Analyze test results

When tests fail, you often need more detail than just “3 tests failed.” You want to know which tests, what the error messages were, and where in your code the failures occurred. Gemini makes this easy:

Show me the test results from the last pipeline

The get_job_test_results tool pulls detailed test data including the names and file locations of each test, pass/fail status, full failure messages and stack traces, and timing information that can help identify slow tests.

If you just want to focus on what broke, you can filter the results:

Show me only the failed tests from the last build

Hunt down flaky tests

Flaky tests are one of the most frustrating problems in any test suite. They pass sometimes and fail other times, eroding your confidence in the build and wasting time when you have to re-run pipelines. Gemini can help you identify them:

Find flaky tests in my project

The find_flaky_tests tool analyzes your test history to identify tests with inconsistent results, giving you a starting point for improving your test suite’s reliability.

Bonus: Using the CircleCI CLI with Gemini

The MCP server gives Gemini access to CircleCI’s cloud APIs, but you can also leverage the CircleCI CLI for local operations. This works particularly well with Gemini CLI (since it can execute terminal commands directly), but you can also ask Gemini Code Assist to run these commands for you in VS Code’s integrated terminal.

Validate your config offline

Run circleci config validate in the terminal

This uses the CircleCI CLI to check your configuration locally, without any API calls. It’s faster and works even when you’re offline.

Run jobs locally

Use the CircleCI CLI to run the build job locally

This executes circleci local execute --job build, which spins up Docker containers that closely mirror the CircleCI environment. It’s a great way to debug tricky job failures without pushing commit after commit.

When to use which

Approach	Best for
MCP server	Checking real pipeline status, fetching actual build logs, analyzing test results, triggering remote builds
CircleCI CLI	Quick offline config validation, running jobs locally for debugging, iterating on config changes faster

The good news is you don’t have to choose. Gemini can use both approaches, and you can mix and match depending on what you need at the moment.

Troubleshooting

The MCP server doesn’t appear

In Gemini CLI: If you run /mcp and don’t see the CircleCI server listed, here are some things to check:

1. Make sure your settings.json file contains valid JSON—even a missing comma or bracket will prevent it from loading. Try pasting it into a JSON validator to check.
2. Verify that you have Node.js 20 or newer installed by running node --version
3. Try running the MCP server manually to see if there are any errors:

CIRCLECI_TOKEN=your-token npx @circleci/mcp-server-circleci@latest

In Gemini Code Assist: If the CircleCI tools aren’t available in agent mode:

1. Make sure you’ve reloaded VS Code after editing settings.json (Command Palette → “Developer: Reload Window”)
2. Verify you’re in agent mode, not regular chat mode
3. Check that the settings.json file is in the correct location (~/.gemini/settings.json)

Gemini can’t find your project

If Gemini doesn’t recognize your project when you ask about pipelines:

1. Check that the project is being followed in your CircleCI dashboard (Projects → your project → Follow Project)
2. Verify your Git remote is configured correctly with git remote -v
3. Make sure your API token has the necessary permissions
4. Try specifying the project explicitly: Get pipeline status for gh/my-org/my-repo

Authentication errors

If you’re getting authentication failures:

1. Check that your token hasn’t expired by visiting User Settings → Personal API Tokens in CircleCI
2. Generate a new token and update your settings.json file
3. Make sure there are no extra spaces or newlines in the token value

Wrapping up

By connecting Gemini with CircleCI’s MCP server, whether you’re using Gemini CLI in your terminal or Gemini Code Assist in VS Code, you’ve given yourself a powerful new workflow that keeps you in your flow state. You can now validate configurations before pushing and catch errors early, trigger pipelines with a simple question instead of clicking through a dashboard, diagnose failed builds using natural language and get actionable suggestions, and analyze test results and track down flaky tests without leaving your development environment.

Every time you don’t have to open a browser tab, navigate to a dashboard, and hunt for information, you save a little bit of mental energy. Those savings add up over a day, a week, a project.

Ready to try it yourself? Sign up for a free CircleCI account and see how much smoother your CI/CD workflow can be.