# How to Integrate Bolt.new with Mercurial - Tool: Bolt.new - Difficulty: Beginner - Time required: 15 minutes - Last updated: April 2026 ## TL;DR Bolt.new has no native Mercurial integration — only GitHub is natively supported. To use Mercurial with a Bolt project, export the project as a ZIP file, extract it locally, and initialize a Mercurial repository with hg init. Push to Bitbucket (which still supports Mercurial) or a self-hosted Hg server. For teams with existing Mercurial infrastructure, this manual workflow is functional but more cumbersome than Git. Most users should use Bolt's native GitHub integration instead. ## Using Mercurial Version Control with Bolt.new Exported Projects Mercurial was once a major force in version control, used by prominent technology companies and beloved for its clean command-line interface and consistent behavior. In 2025-2026, Mercurial usage has declined significantly — Bitbucket removed Mercurial support in 2020 (though community-maintained Mercurial hosting remains available), and most organizations have migrated to Git. However, some enterprises with legacy infrastructure, particularly those that built tooling around Mercurial workflows, still use it actively. Bolt.new's version control integration is GitHub-only. The Git panel in Bolt's editor connects to GitHub via OAuth and pushes to GitHub repositories with one click. There is no equivalent for Mercurial, GitLab (which also requires the manual path), Bitbucket, or any non-GitHub Git host. This is a deliberate design decision — GitHub's dominance and Bolt's integration with the broader GitHub ecosystem (Actions, Copilot, Pages) makes it the obvious choice for Bolt's target audience. For teams committed to Mercurial, the workflow described in this guide works reliably — it is just more manual than the native GitHub integration. The core pattern is: build features in Bolt, export the updated project as a ZIP, extract the changes, review what changed, commit to Mercurial, and push to your Hg host. This is the same pattern required for GitLab, Bitbucket, and any other non-GitHub version control system. The primary trade-off is speed: Git users push from Bolt in one click; Mercurial users export, extract, and commit manually. ## Before you start - A Bolt.new account with a project ready to version control - Mercurial installed locally — download at mercurial-scm.org (available for Windows, macOS via Homebrew, Linux via package manager) - A Mercurial hosting account: Bitbucket no longer supports Mercurial directly, so use RhodeCode (free community edition at rhodecode.com), Kallithea, or a self-hosted Hg server - Basic familiarity with the terminal and command-line tools - Optional: hg-git extension if you want to bridge between Mercurial and GitHub repositories ## Step-by-step guide ### 1. Understand the Landscape: Mercurial in 2026 Before committing to a Mercurial workflow for Bolt projects, it is worth understanding the current state of the Mercurial ecosystem. This context will help you decide whether to proceed with Mercurial or migrate to Git. Mercurial itself is still maintained — the mercurial-scm.org project continues releasing updates, and the core VCS works well for teams that have invested in it. The tool is conceptually simpler than Git in several ways: the mental model of changesets, bookmarks instead of branches for most workflows, and more consistent command behavior across platforms. However, the hosting landscape has changed significantly. Bitbucket dropped Mercurial support in June 2020 — the platform is now Git-only. Organizations that were Bitbucket-Mercurial users had to migrate somewhere: many chose GitHub or GitLab (converting to Git), some set up self-hosted Mercurial servers using RhodeCode or Kallithea, and some moved to Sourcehut (which supports Mercurial natively). For Bolt.new specifically, the decision point is straightforward. If your organization has active Mercurial infrastructure with custom tooling, CI/CD pipelines, and workflows that would be expensive to migrate, the manual export workflow described here is a reasonable solution. If you are starting fresh or could migrate with modest effort, using Git and Bolt's native GitHub integration gives you one-click pushes, automatic deploys via Netlify, and access to the GitHub Actions ecosystem. Most new Bolt users should use GitHub. This guide is for the Mercurial cases where migration is not practical in the short term. ``` # Install Mercurial: # macOS (Homebrew): brew install mercurial # Ubuntu/Debian: sudo apt-get install mercurial # Verify installation: hg --version # Should print: Mercurial SCM (version 6.x.x) ``` **Expected result:** Mercurial is installed and the hg --version command prints a version number. You have decided whether to proceed with native Mercurial or use hg-git as a bridge to GitHub. ### 2. Export Your Bolt Project Bolt's native GitHub integration (the Git panel) only works with GitHub. For Mercurial, you use the manual export workflow: download the project as a ZIP file from Bolt's toolbar. In your Bolt project, click the download icon in the top toolbar — it typically appears as a downward-pointing arrow or a box with an arrow. Bolt packages your entire project file system (all source files, configuration files, package.json) into a ZIP archive and downloads it to your browser's default download location. Notable items NOT included in the Bolt ZIP export: node_modules/ (correct — you will run hg add and the .hgignore will exclude this), the Bolt Secrets tab values (your API keys and environment variables — you will need to recreate these in a local .env file), and Bolt's internal Version History (this is Bolt's internal undo system, not part of the exported code). After downloading, create an organized folder structure on your local machine for managing Bolt exports. A dedicated directory like ~/projects/bolt-projects/ with a named subfolder for each project works well. Extract the ZIP into this folder, preserving the original project folder structure. Before initializing the Mercurial repository, take a moment to review what was exported by running ls -la in the project directory. You should see standard Vite or Next.js project files: package.json, src/, public/, configuration files (vite.config.ts or next.config.js), and other project-specific files. The presence of package.json is important — it confirms Bolt exported a proper Node.js project that Mercurial (or any VCS) can version control. ``` # Create a projects directory and extract the Bolt ZIP: mkdir -p ~/projects/bolt-projects/your-project-name cd ~/projects/bolt-projects/your-project-name # On macOS, unzip the downloaded file: unzip ~/Downloads/bolt-project-export.zip -d . # Verify the project structure: ls -la # Expected: package.json, src/, public/, vite.config.ts or next.config.js ``` **Expected result:** The Bolt project is extracted to a local folder. All source files are present, package.json is in the project root. ### 3. Initialize a Mercurial Repository and Create .hgignore With the Bolt project extracted locally, initialize a Mercurial repository and configure what should be tracked versus ignored. This is similar to how Git uses .gitignore, but Mercurial uses .hgignore with its own pattern syntax. Mercurial's .hgignore file supports two pattern syntax modes: regexp (regular expressions, the default) and glob (shell-style wildcards). For most Bolt project ignores, the glob syntax is more readable and easier to write. Specify the syntax at the top of the .hgignore file. Key directories and files to exclude from Mercurial tracking: node_modules/ (hundreds of megabytes of dependencies — always regenerated by npm install), dist/ and .next/ (build output — always regenerated by npm run build), .env and .env.local (API keys and secrets — never commit these to version control), and .bolt/ (Bolt's internal project metadata if it was included in the export). After creating .hgignore, run hg init to create the Mercurial repository, then hg add to stage all non-ignored files. Review what was staged with hg status — files marked with 'A' are added and will be included in the first commit. If any secret files or large binary files appear in the hg status output, add them to .hgignore before committing. ``` # Navigate to the project directory: cd ~/projects/bolt-projects/your-project-name # Create .hgignore: cat > .hgignore << 'EOF' syntax: glob # Dependencies (regenerated by npm install) node_modules/ .pnp .pnp.js # Build output (regenerated by npm run build) dist/ build/ .next/ out/ # Environment files (contain secrets) .env .env.local .env.development.local .env.test.local .env.production.local # Bolt internal .bolt/ # macOS .DS_Store # Logs npm-debug.log* *.log EOF # Initialize Mercurial repository: hg init # Add all non-ignored files: hg add # Review what will be committed: hg status ``` **Expected result:** A Mercurial repository is initialized (.hg/ directory exists). hg status shows all source files as 'A' (added). No node_modules/, dist/, or .env files appear in the status output. ### 4. Make the Initial Commit and Push to a Hg Host With files staged via hg add, make the initial commit with a descriptive message describing what this Bolt project contains. Then push to your Mercurial hosting platform. For self-hosted Mercurial: Kallithea, RhodeCode, and Gogs (which supports Mercurial) are common choices. Create a new repository on your hosting platform, note the SSH or HTTPS URL, and configure Mercurial's .hg/hgrc file with the remote URL. For Bitbucket alternative (since Bitbucket dropped Mercurial): Sourcehut (sr.ht) is a modern development platform that supports Mercurial natively alongside Git. Create an account at sourcehut.org, set up your SSH key, and push to a Mercurial repository. Sourcehut also has CI (builds.sr.ht) that can run npm run build on pushes. After the initial push, establish a routine for subsequent Bolt updates. When you make changes in Bolt and want to sync them to Mercurial: export a new ZIP from Bolt, extract it to a temporary folder, copy only the changed files over your existing Mercurial repository folder (or use diff/patch to identify and apply changes), then commit and push the updates. This is more manual than Git's approach but achieves the same version control result. An important consideration about the WebContainer limitation: Bolt's development environment cannot receive incoming webhooks or connect to external services using raw TCP. Once you export the project and push to your Mercurial host, any Hg-based CI/CD pipeline can build and deploy the app in a real server environment where these limitations do not apply. Your existing Mercurial-integrated build systems work normally with the exported Bolt code. ``` # Make the initial commit: hg commit -m "Initial commit: Bolt.new project export" # Configure remote repository in .hg/hgrc: # [paths] # default = https://your-hg-host.com/yourname/your-project # Using a text editor or command line: cat >> .hg/hgrc << 'EOF' [paths] default = https://your-hg-host.com/yourname/your-project EOF # Push to remote: hg push # For first push you may need: hg push --new-branch # For subsequent Bolt updates: # 1. Export new ZIP from Bolt # 2. Extract and copy changed files to repo directory # 3. Check what changed: hg status hg diff # 4. Commit and push: hg commit -m "Update: [describe what changed in Bolt]" hg push ``` **Expected result:** The initial commit is in your local Mercurial repository and pushed to the remote host. The project history shows the initial commit with all source files tracked. ## Best practices - Use Git and Bolt's native GitHub integration if you have any choice in the matter — the one-click push in Bolt's Git panel is vastly faster than the manual ZIP export cycle required for Mercurial. - If you must use Mercurial, consider the hg-git extension as a bridge: work in Mercurial locally but push to GitHub for Bolt's native bidirectional sync, avoiding the manual export cycle. - Create a .hgignore file before the first hg add to prevent accidentally tracking node_modules/, .env files, and build output directories. - Use descriptive commit messages that explain what changed from the Bolt perspective — 'Add payment integration step 3: webhook handler' is more useful than 'Update from Bolt export'. - Keep Bolt exports dated and organized (bolt-export-2026-04-22/) in a separate folder from your Mercurial repository to make it easy to compare what changed between exports using hg diff. - For teams with existing Mercurial CI/CD, verify that the CI system can build Vite and Next.js projects — Bolt generates modern JavaScript toolchains that require Node.js 18+ and may need CI configuration updates. - Consider migrating to Git strategically — use the Bolt project as the opportunity to introduce Git in your workflow, since Bolt itself is the primary reason to be working with it. ## Use cases ### Maintaining a Bolt Project in a Legacy Mercurial Repository An organization with existing Mercurial infrastructure wants to use Bolt for frontend development while keeping all code in their Hg-based system. Export from Bolt periodically, commit the changes to the Mercurial repository, and use existing Hg-based CI/CD pipelines to build and deploy the updated application. ### One-Time Export for Long-Term Local Development Use Bolt to rapidly prototype an application, export the completed prototype to a Mercurial repository, and continue development using local tools and Mercurial for version control. Bolt is used for the initial build only; all subsequent development happens outside Bolt with Mercurial tracking changes. ### Using Mercurial Alongside GitHub via Repository Mirroring Connect Bolt to GitHub natively for one-click pushes, and set up Mercurial's hg-git extension or a Bitbucket mirror to sync the GitHub repository to your Mercurial infrastructure. This gives you Bolt's native GitHub integration while keeping your Hg-based workflows intact. ## Troubleshooting ### hg push fails with 'ssl: certificate verify failed' when pushing to a self-hosted Mercurial server Cause: The self-hosted Mercurial server is using a self-signed SSL certificate that Mercurial cannot verify against its trusted certificate authorities. Solution: For internal servers using self-signed certificates, add the certificate fingerprint to ~/.hgrc. Get the fingerprint with: openssl s_client -connect your-hg-host.com:443 < /dev/null 2>&1 | openssl x509 -fingerprint -noout. Then add it to ~/.hgrc under [hostfingerprints]. Alternatively, for a less secure but quick fix, add 'insecure = true' under [hostfingerprints] for the specific host. ``` # Add to ~/.hgrc (global Mercurial config): [hostfingerprints] your-hg-host.com = SHA256:abc123...your-fingerprint-here # Or for HTTP (not HTTPS) hosts: [paths] default = http://your-hg-host.com/yourname/repo ``` ### After extracting a new Bolt ZIP over an existing repository folder, hg status shows hundreds of unexpected modified files Cause: The Bolt ZIP export sometimes includes files with slightly different line endings or whitespace, making Mercurial detect them as modified even when the logical content has not changed. Solution: Configure Mercurial's eol extension to normalize line endings. Add the eol extension to ~/.hgrc and create a .hgeol file in the project root that sets the line ending policy. This ensures consistent line endings regardless of whether files came from Bolt's export or manual edits. ``` # .hgeol file in project root: [patterns] **.js = native **.ts = native **.tsx = native **.json = native # ~/.hgrc: [extensions] eol = ``` ### The hg-git extension is not working for bridging Mercurial to GitHub for Bolt's native integration Cause: The hg-git extension (dulwich) requires a compatible version of Python and the dulwich library to be installed. Version mismatches between Mercurial, hg-git, and dulwich are common. Solution: Install hg-git using pip with the exact version compatible with your Mercurial installation: pip install hg-git. Enable it in ~/.hgrc under [extensions]: hggit =. If version conflicts persist, consider using git-remote-hg (a Git extension that enables git commands against Mercurial repos) instead, which goes in the opposite direction. ``` # Install hg-git: pip3 install hg-git # Enable in ~/.hgrc: [extensions] hggit = # Clone a GitHub repo using hg-git: hg clone git+https://github.com/yourname/your-bolt-project.git # Push back to GitHub from Mercurial: hg push ``` ## Frequently asked questions ### Does Bolt.new support Mercurial repositories natively? No — Bolt.new only supports GitHub natively through its built-in Git panel. For Mercurial, you must use the manual export workflow: download the project as a ZIP, extract it locally, and use standard hg commands to commit and push. There is no planned Mercurial integration for Bolt based on current documentation. ### Can I use Bitbucket with Bolt.new for Mercurial repositories? Bitbucket removed Mercurial support in June 2020 and is now a Git-only platform. If you have an existing Bitbucket Mercurial repository from before 2020, it was archived and is no longer accepting pushes. For current Mercurial hosting, options include Sourcehut (sr.ht), RhodeCode, Kallithea, or a self-hosted Hg server. If you want to use Bitbucket with Bolt, you would use Bitbucket's Git functionality with the same manual export workflow. ### Is it worth migrating from Mercurial to Git just to get Bolt's native GitHub integration? For most teams, yes — especially if Bolt is going to be your primary development environment. The native GitHub integration saves significant time: one-click pushes, automatic Netlify deployments on every push, GitHub Actions for CI/CD, and no manual ZIP export cycle. Migrating a Mercurial repository to Git is straightforward using hg-fast-export or the GitHub Importer. The migration cost is typically a day of work for a small-to-medium project, after which the workflow is permanently faster. ### Can the hg-git extension give me the same experience as Bolt's native GitHub integration? Partially — hg-git lets you push Mercurial changesets to a GitHub repository, which would then trigger automatic Netlify deploys and allow Bolt to pull the changes. However, you lose the one-click push in Bolt's Git panel (you would push from your local terminal using Mercurial commands) and the bidirectional sync requires careful management of the Git-Mercurial bridge. It is more functional than pure Mercurial but still more complex than native Git. ### How do I handle merge conflicts when multiple developers are updating the Mercurial repository between Bolt exports? Mercurial handles merge conflicts similarly to Git — when two changesets modify the same file, hg merge creates a merge changeset that must resolve the conflict. For Bolt specifically: if a teammate commits changes to the Mercurial repo while you are building in Bolt, your next ZIP export may be based on an older state. After extracting the new ZIP, run hg pull and hg merge to incorporate the team changes, then resolve any conflicts manually before committing. This is the same challenge as with any VCS in a team environment. --- Source: https://www.rapidevelopers.com/bolt-ai-integrations/mercurial © RapidDev — https://www.rapidevelopers.com/bolt-ai-integrations/mercurial