# How to Build and Deploy the ChatMCP Web Version to GitHub Pages

> Learn to build and deploy the ChatMCP web version to GitHub Pages using GitHub Actions or manual Flutter deployment. Effortlessly share your web app.

- Repository: [刀刀/chatmcp](https://github.com/daodao97/chatmcp)
- Tags: how-to-guide
- Published: 2026-02-28

---

**You can deploy the ChatMCP web client to GitHub Pages either automatically via the included GitHub Actions workflow or manually using Flutter's `build web` command combined with a force-push to the `gh-pages` branch.**

ChatMCP is a Flutter-based multi-platform AI chat client maintained in the `daodao97/chatmcp` repository. The web target compiles to static assets (HTML, JavaScript, and CSS) that any static-site host can serve, and the project includes a ready-made CI pipeline that handles the entire deployment process.

## Architecture Overview

The deployment pipeline consists of three integrated layers. **Flutter SDK** generates a pure-web build in the `build/web/` directory, producing an [`index.html`](https://github.com/daodao97/chatmcp/blob/main/index.html) entry point that loads the compiled Dart code. The build command **`flutter build web --base-href /chatmcp/`** configures the app to run under the `/chatmcp/` sub-path, which matches the repository's GitHub Pages URL structure at `https://daodao97.github.io/chatmcp`.

**GitHub Actions** automates the process through [`.github/workflows/build-web.yml`](https://github.com/daodao97/chatmcp/blob/main/.github/workflows/build-web.yml). This workflow installs Flutter, fetches dependencies, builds the release bundle, and uses **`peaceiris/actions-gh-pages@v4`** to publish the contents of `build/web/` to the **`gh-pages`** branch. **GitHub Pages** then serves these static files directly from that branch.

## Prerequisites

Before building or deploying, ensure your environment meets these requirements:

- **Flutter SDK** (≥ 3.32.5) installed and available on your system PATH. The repository README provides platform-specific installation instructions for macOS, Linux, and Windows.
- A **GitHub Personal Access Token** with `repo` scope. The automated workflow expects this as the `MY_GITHUB_TOKEN` repository secret.

## Automated CI Deployment

The recommended approach uses the project's built-in workflow to deploy on every push to `main`.

When you push commits to the `main` branch, the **Build & deploy** workflow in [`.github/workflows/build-web.yml`](https://github.com/daodao97/chatmcp/blob/main/.github/workflows/build-web.yml) triggers automatically. The job runs on Ubuntu, executes `flutter build web --base-href /chatmcp/`, uploads the `build/web/` directory as an artifact, and deploys it to the `gh-pages` branch. No manual intervention is required after the initial secret configuration.

```yaml

# .github/workflows/build-web.yml (key steps)

- name: Build release project
  run: flutter build web --base-href /chatmcp/

- name: Deploy to gh-pages
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.MY_GITHUB_TOKEN }}
    publish_dir: build/web

```

After the workflow completes, GitHub Pages serves the updated site at your repository's Pages URL within minutes.

## Manual Deployment

If you need to deploy outside of CI or troubleshoot locally, build and push manually using Git commands.

First, compile the production bundle:

```bash
flutter pub get
flutter build web --base-href /chatmcp/

```

This generates static files in `build/web/`. Next, create an orphan `gh-pages` branch, replace its contents with the build output, and force-push:

```bash

# Switch to orphan branch (create if missing)

git checkout --orphan gh-pages

# Clean the branch

git rm -rf .

# Copy build artifacts

cp -r build/web/* .

# Commit and deploy

git add .
git commit -m "Deploy ChatMCP web version"
git push origin gh-pages --force

# Return to main branch

git checkout main

```

GitHub Pages will detect the new commit on `gh-pages` and update the live site.

## Local Development and Testing

To verify changes before deploying, run the web app locally with hot-reload enabled:

```bash

# Install dependencies

flutter pub get

# Launch in Chrome for development

flutter run -d chrome

```

For a production preview that matches the GitHub Pages environment exactly, use the release build command locally and serve the `build/web/` directory with any static file server.

## Understanding the Base Href Configuration

The **`--base-href /chatmcp/`** parameter is critical for correct asset loading. Because GitHub Pages serves project repositories under a sub-directory (`https://<user>.github.io/<repo>/`), Flutter must generate relative URLs that include this path. Without this flag, the browser requests assets from the domain root, resulting in 404 errors. The CI workflow and manual commands both include this flag to ensure CSS and JavaScript bundles load correctly.

## Summary

- **ChatMCP** compiles to static web assets using Flutter's `build web` command.
- The **[`.github/workflows/build-web.yml`](https://github.com/daodao97/chatmcp/blob/main/.github/workflows/build-web.yml)** pipeline automates builds and publishes to the **`gh-pages`** branch using `peaceiris/actions-gh-pages@v4`.
- Always use **`--base-href /chatmcp/`** when building to match the GitHub Pages URL structure.
- You can deploy **automatically** on every push to `main` or **manually** via git commands when needed.
- The **Makefile** in the repository includes a `build-web` target as a shortcut for the CI-style build command.

## Frequently Asked Questions

### Why does the build require the `--base-href` flag?

GitHub Pages serves project repositories under a sub-path (e.g., `/chatmcp/`), not at the domain root. The `--base-href /chatmcp/` parameter tells Flutter to prefix all asset URLs in [`index.html`](https://github.com/daodao97/chatmcp/blob/main/index.html) with this path, ensuring that JavaScript and CSS files load from the correct location rather than returning 404 errors.

### What Flutter version is required to build ChatMCP?

The repository requires **Flutter ≥ 3.32.5**. You can verify your installation by running `flutter --version`. Building with older versions may result in compilation errors or missing web-specific features used by the application.

### How do I update the deployed site after making changes?

If you are using the automated workflow, simply push your changes to the `main` branch. The GitHub Action will rebuild and redeploy automatically. For manual updates, rerun the Flutter build command and repeat the git checkout, copy, commit, and force-push steps to the `gh-pages` branch.

### Can I deploy the web version to hosts other than GitHub Pages?

Yes. The `build/web/` directory contains standard static files (HTML, JS, CSS) that any static hosting provider (Vercel, Netlify, Cloudflare Pages, or an Nginx server) can serve. When deploying to a root domain or different sub-path, adjust or omit the `--base-href` flag to match your hosting configuration.