GitHub Integration with Bolt.new: My Practical Guide | Ryan Katayi

I use Bolt.new with GitHub to get automatic backups, clean version history, and a workflow that fits real teams. This writeup collects the steps, gotchas, and habits that keep things smooth.

Why I connect Bolt to GitHub

Versioned backups in a repo I control
Switch freely between Bolt and local dev without losing history
Use my existing CI, review, and deployment pipelines
Keep branches isolated so work in progress does not pollute production

What this setup can do

Create a new private repo from any Bolt project
Import an existing repo into Bolt and keep working there
Auto commit edits that pass runtime checks
Auto fetch external commits on a short poll interval

Notes

Merging is not available inside Bolt. I open pull requests and merge in GitHub.
The integration currently requires a personal GitHub account. Organization accounts are not supported yet.

Connect Bolt to GitHub

In the Bolt project, open Integrations then choose GitHub
Authorize the StackBlitz app when prompted
Pick Create repository for a new repo or Import from URL to bring an existing repo into Bolt
New repos start as private on main. I switch visibility in GitHub settings later if needed

Tip: when importing, I can select from my repos or paste any public URL. Private repos I own also work after authorization.

Branching model I use

Start work on a short lived feature branch created in Bolt or in GitHub
Keep main protected. Require PRs and checks
Treat each branch as its own context. Bolt agent memory sees only the active branch, which helps avoid cross talk

Create and switch branches in Bolt

Click the GitHub icon in the left sidebar
Create or select a branch

Merge strategy

Open a pull request in GitHub
Run checks and code review
Merge in GitHub, not in Bolt

Commits and sync

How commits work in Bolt

Bolt auto commits changes that do not have runtime errors
If a change in GitHub lands while Bolt is about to commit, Bolt resolves the race by applying the Bolt version. Plan for that

How fetching works

Bolt polls for external changes on a short interval and updates the workspace

My safeguards

Keep work off main. Use feature branches
Enable branch protection with required status checks
If I am collaborating, I coordinate pushes to the same branch or I use a PR based flow to avoid silent overwrites

Recommended CI and deployments

Connect GitHub Actions to run lint, typecheck, and tests on pull request and on merge to main
If I deploy from GitHub, I keep the deploy job in Actions or in my provider such as Netlify, Vercel, or Cloudflare
Secrets live in the CI provider. Bolt does not need production secrets for this flow

Example Actions triggers

name: ci
on:
  pull_request:
    branches: [ main ]
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test --if-present

Handling access and disconnects

To revoke access, go to GitHub Settings, Applications, Authorized OAuth Apps, find StackBlitz, and revoke
If I signed up for Bolt with GitHub and need to move the integration to another Bolt account, I create a password login on the old account, remove GitHub from its credentials, then connect GitHub on the new account

Common pitfalls I watch for

Race conditions between a Bolt auto commit and an incoming GitHub push can overwrite the remote with the Bolt version. Work on branches and use PRs
Merging in Bolt is not available. Always merge in GitHub
Organization repos are not supported. Use a personal account or mirror to an org with a separate GitHub workflow
If I duplicate a Bolt project, I reconnect integrations. Publishing targets and tokens do not carry over

My day to day flow

Create or import repo
Create a feature branch
Build in Bolt and let it auto commit safe changes
Push a PR from that branch
Run CI and review
Merge in GitHub
Deploy from GitHub

FAQ I get from teammates

Can we make the repo public

Yes. New repos are private by default. Flip to public in GitHub settings when ready

Can Bolt see changes I make locally

Yes. Bolt polls for external commits and updates the workspace

Why do my changes keep overwriting teammate commits

Likely we are both working on the same branch while Bolt auto commits. Use feature branches and PRs

Can I use this with org repos

Not yet. I use a personal repo and mirror or transfer later if needed

Extras I like

Self hosting the open source variant for experiments does not change the GitHub flow. The integration habits above still apply
Pair with Netlify, Vercel, or Cloudflare for deploys triggered by GitHub merges

Quick checklist

Personal GitHub account connected
Branch protection on main
CI set up on PR and main
Secrets stored in CI or the hosting provider
Work only on feature branches
Merge in GitHub, not in Bolt