How to Integrate Bolt.new with CircleCI

Before CircleCI can automate anything, your Bolt project needs to live in a GitHub repository. CircleCI connects to GitHub (and GitLab/Bitbucket) to monitor for new commits. If your Bolt project is not yet on GitHub, this step sets that up. In your Bolt project, look for the Git panel icon in the left sidebar (it looks like a branching tree diagram). If you have not connected GitHub yet, click 'Connect GitHub' and authorize Bolt through GitHub's OAuth flow. Once connected, click 'Push to GitHub' and choose 'Create new repository.' Give the repository a meaningful name — something like 'my-bolt-app' — and choose public or private based on your preference. Click 'Create and push' and Bolt will commit all your project files to the new repository. For the CircleCI pipeline to work correctly, your repository needs to have the standard Bolt project structure: a package.json with a build script ('npm run build' for both Vite and Next.js), the src/ directory with your components, and any configuration files (vite.config.ts, next.config.js, tailwind.config.js). Bolt generates all of these automatically. Note on the GitHub-CircleCI-Netlify flow: Bolt does not communicate with CircleCI directly. The integration is: Bolt pushes code to GitHub → GitHub notifies CircleCI via webhook → CircleCI runs the pipeline → CircleCI deploys to Netlify/Vercel. Each step is independent. If you later want to bypass CircleCI for a quick deploy (e.g., during development), you can still use Bolt's publish button directly to Bolt Cloud or Netlify — the CircleCI pipeline only runs when commits reach GitHub.

1# Verify your repository has the expected structure before adding CircleCI:
2ls -la
3# Should see:
4# package.json
5# src/
6# public/
7# vite.config.ts (or next.config.js)
8# .gitignore
9# tsconfig.json
10
11# Check that the build script exists:
12cat package.json | grep -A5 '"scripts"'

After setting up the GitHub repository, the next step is connecting it to CircleCI so the platform monitors for new commits. Go to circleci.com and sign in with your GitHub account. CircleCI uses GitHub OAuth, so it automatically detects repositories you have access to. On the CircleCI dashboard, click 'Projects' in the left sidebar, then click 'Set Up Project' next to the repository that contains your Bolt project. CircleCI will ask how you want to configure the pipeline — choose 'Create my own config' or 'Use an existing config' if you plan to add the config file manually. CircleCI will offer to create a default config.yml. You can let it generate a starter configuration and then customize it, or skip this and add the config file directly to your GitHub repository in the next step. Either approach results in the same outcome — a .circleci/config.yml file in the repository root that defines the pipeline. An important note about CircleCI's free tier: as of 2026, the free tier (called the 'Free' plan) provides 6,000 build credits per month on Linux infrastructure. Build credit consumption depends on resource class — using the 'small' resource class (1 vCPU, 2GB RAM) consumes 5 credits per minute. A 4-minute Bolt Vite build uses 20 credits. With 6,000 credits per month, you can run approximately 300 builds per month on the free tier. This is generous for development and staging workflows; production pipelines with high commit frequency may require upgrading to the paid plan.

The pipeline configuration file tells CircleCI what to do when new code is pushed. For a Bolt.new project, the pipeline has three main jobs: install dependencies, build the project, and deploy the output. The configuration format is YAML and lives in a .circleci/ directory at your repository root. You can create this file in two ways: add it directly in the Bolt editor (create a new file at .circleci/config.yml in Bolt's file tree), or add it through GitHub's web interface after pushing the project. Either approach works — the file just needs to be committed to the repository. The configuration below works for both Vite and Next.js Bolt projects. It uses Node.js 18, caches node_modules between builds for faster runs (saving approximately 30-60 seconds per build), runs npm run build, and deploys to Netlify. Adjust the deploy step if you are using Vercel or another platform. Key configuration decisions: Using the 'small' resource class keeps the build within the free tier's budget. The node_modules cache uses a checksum of package-lock.json as the cache key — whenever you add or remove packages in Bolt (which updates package-lock.json), CircleCI automatically invalidates the cache and does a fresh install. The deploy job depends on the build job completing successfully, so a failed build prevents deployment. The `only: main` filter under branches means the pipeline only runs on pushes to the main branch — which is where Bolt always pushes. If you set up feature branches for manual work, those branches will not trigger deployments (only build verification). This is typically the desired behavior for production deployments.

1# .circleci/config.yml
2version: 2.1
3
4orbs:
5  node: circleci/node@5.2.0
6
7jobs:
8  build:
9    docker:
10      - image: cimg/node:18.17
11    resource_class: small
12    steps:
13      - checkout
14      - node/install-packages:
15          pkg-manager: npm
16          cache-path: node_modules
17          override-ci-command: npm ci
18      - run:
19          name: Build project
20          command: npm run build
21      - persist_to_workspace:
22          root: .
23          paths:
24            - dist      # Vite output directory
25            # - .next   # Uncomment for Next.js projects
26
27  deploy-netlify:
28    docker:
29      - image: cimg/node:18.17
30    resource_class: small
31    steps:
32      - attach_workspace:
33          at: .
34      - run:
35          name: Install Netlify CLI
36          command: npm install -g netlify-cli
37      - run:
38          name: Deploy to Netlify
39          command: |
40            netlify deploy \
41              --dir=dist \
42              --site=$NETLIFY_SITE_ID \
43              --auth=$NETLIFY_AUTH_TOKEN \
44              --prod
45
46workflows:
47  build-and-deploy:
48    jobs:
49      - build:
50          filters:
51            branches:
52              only: main
53      - deploy-netlify:
54          requires:
55            - build
56          filters:
57            branches:
58              only: main

Your CircleCI pipeline needs credentials to deploy to Netlify — specifically the Netlify auth token and site ID. These must be stored as CircleCI environment variables, not hardcoded in the config.yml file (which would expose them in your GitHub repository). To get your Netlify auth token: log in to Netlify, go to User Settings > Applications > Personal access tokens, click 'New access token,' give it a name like 'CircleCI Deploy,' and copy the generated token. You will not be able to see it again after closing the dialog. To get your Netlify site ID: if you have not deployed to Netlify yet, create a new site first (either a blank site from the Netlify dashboard or a quick manual deploy). Then go to the site's Settings > General > Site details and copy the 'Site ID' value (a UUID like 'abc12345-1234-1234-1234-abcdefabcdef'). To add these to CircleCI: in the CircleCI dashboard, go to your project's settings (click the gear icon next to the project name), then select 'Environment Variables' in the left sidebar. Click 'Add Variable' and add: NETLIFY_AUTH_TOKEN with the token value, and NETLIFY_SITE_ID with the site ID value. CircleCI encrypts these values and makes them available to pipeline runs as standard environment variables. If your Bolt project also uses API keys (for Supabase, OpenAI, or other services), add those here as well — these values will be available during the build and baked into the output for client-side variables, or available to the Netlify deployment for server-side variables. For client-side Vite variables (VITE_ prefix), they need to be present during the build step so Vite can inline them.

1# Environment variables to add in CircleCI project settings:
2# NETLIFY_AUTH_TOKEN = your-netlify-personal-access-token
3# NETLIFY_SITE_ID = your-netlify-site-id-uuid
4#
5# For Bolt projects with Supabase:
6# VITE_SUPABASE_URL = https://yourproject.supabase.co
7# VITE_SUPABASE_ANON_KEY = your-anon-key
8#
9# For Bolt projects with Next.js API routes:
10# Any server-side env vars that need to be set at build time

With everything configured, test the complete pipeline by making a change in Bolt and pushing to GitHub. This verifies that the entire automation chain works end to end. In Bolt, make a visible change — update some text on the homepage, change a button color, or add a new component. Then use Bolt's Git panel to push to GitHub. The push should take 10-30 seconds. Once it completes, go to your CircleCI dashboard and watch the pipeline trigger automatically. The build job starts within 30-60 seconds of the GitHub push. Monitor the pipeline progress in CircleCI. You will see each step execute: 'Checkout code,' 'Restore cache,' 'Install packages,' 'Build project,' and then in the deploy job, 'Deploy to Netlify.' Each step shows its output and duration. If any step fails, the logs will show the exact error — this is particularly useful for catching build errors that were not visible in Bolt's preview. A key insight about this workflow: Bolt's WebContainer runs Node.js in a browser environment with some differences from a standard Node.js build environment. CircleCI runs a true Linux Node.js environment, which means it may catch build errors that Bolt's preview missed. TypeScript strict mode errors, missing dependencies, and environment-specific issues all surface in the CircleCI build. This is actually a feature — catching issues before they reach production is the core purpose of CI. Once the pipeline completes successfully, the deployed Netlify URL will have your latest Bolt changes live. From this point on, every push from Bolt automatically triggers a new deployment through CircleCI. You can monitor deployment history, re-run failed builds, and view build logs from the CircleCI dashboard without needing to open Bolt at all.

1# Check CircleCI pipeline status via CLI (optional):
2npm install -g @circleci/circleci-cli
3circleci setup  # authenticate with your API token
4circleci pipeline list  # view recent pipelines
5
6# Or use the CircleCI web dashboard at:
7# https://app.circleci.com/pipelines/github/YOUR_USERNAME/YOUR_REPO