From 72fe23c77b48603d02d38ffc64b039bc45e6ef06 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Feb 2026 18:41:55 +0000 Subject: [PATCH 1/4] Initial plan From 687101ffdfc428d2e805b86713e185c63c7ffc9f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Feb 2026 18:44:10 +0000 Subject: [PATCH 2/4] Add comprehensive GitHub Pages hosting guide Co-authored-by: Caleb-Lite <175520785+Caleb-Lite@users.noreply.github.com> --- GITHUB_PAGES_HOSTING.md | 281 ++++++++++++++++++++++++++++++++++++++++ README.md | 4 + 2 files changed, 285 insertions(+) create mode 100644 GITHUB_PAGES_HOSTING.md diff --git a/GITHUB_PAGES_HOSTING.md b/GITHUB_PAGES_HOSTING.md new file mode 100644 index 00000000000..08394490036 --- /dev/null +++ b/GITHUB_PAGES_HOSTING.md @@ -0,0 +1,281 @@ +# Hosting OpenCode on GitHub Pages + +This guide explains how to host your own version of OpenCode on GitHub Pages, allowing you to work with your other repositories and customize the deployment to your needs. + +## Overview + +OpenCode is an AI-powered coding agent that can be self-hosted on various platforms, including GitHub Pages. This guide will walk you through setting up your own instance that integrates with your GitHub repositories. + +## Prerequisites + +Before you begin, ensure you have: + +- A GitHub account +- Git installed on your local machine +- Node.js 18+ or Bun 1.3+ installed +- Basic knowledge of Git and GitHub workflows + +## Fork and Clone the Repository + +1. **Fork the OpenCode repository** to your GitHub account: + - Visit https://github.com/anomalyco/opencode + - Click the "Fork" button in the top-right corner + - Select your account as the destination + +2. **Clone your forked repository**: + ```bash + git clone https://github.com/YOUR_USERNAME/opencode.git + cd opencode + ``` + +3. **Install dependencies**: + ```bash + bun install + # or if using npm + npm install + ``` + +## Configure for GitHub Pages + +### Option 1: Deploy Documentation Site + +If you want to host the OpenCode documentation on GitHub Pages: + +1. **Navigate to the docs package**: + ```bash + cd packages/docs + ``` + +2. **Build the documentation**: + ```bash + bun run build + # or + npm run build + ``` + +3. **Create a GitHub Actions workflow** for automatic deployment: + + Create `.github/workflows/gh-pages.yml` in your repository root: + ```yaml + name: Deploy to GitHub Pages + + on: + push: + branches: + - main + - dev + workflow_dispatch: + + permissions: + contents: read + pages: write + id-token: write + + concurrency: + group: "pages" + cancel-in-progress: false + + jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Bun + uses: oven-sh/setup-bun@v2 + with: + bun-version: latest + + - name: Install dependencies + run: bun install + + - name: Build documentation + run: | + cd packages/docs + bun run build + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: './packages/docs/dist' + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 + ``` + +### Option 2: Deploy the Full Application + +If you want to host the entire OpenCode application: + +1. **Build the application**: + ```bash + bun run build + ``` + +2. **Configure the base path** for GitHub Pages in your build configuration. + + For the web package, update `packages/web/astro.config.mjs`: + ```javascript + export default defineConfig({ + site: 'https://YOUR_USERNAME.github.io', + base: '/opencode', + // ... other config + }); + ``` + +3. **Use the GitHub Actions workflow** (similar to Option 1, but adjust the build path). + +## Enable GitHub Pages + +1. Go to your repository on GitHub +2. Click on **Settings** → **Pages** +3. Under **Source**, select: + - **Source**: GitHub Actions (recommended) + - Or if deploying manually: **Deploy from a branch** and select `gh-pages` branch + +## Configure Repository Access + +To allow your hosted OpenCode instance to work with your other repositories: + +1. **Generate a Personal Access Token (PAT)**: + - Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic) + - Click "Generate new token (classic)" + - Select scopes: `repo`, `workflow`, `read:org` + - Save the token securely + +2. **Add the token to your repository secrets**: + - Go to your forked repository Settings → Secrets and variables → Actions + - Click "New repository secret" + - Name: `GH_PAT` or `GITHUB_TOKEN` + - Value: Your personal access token + +3. **Configure OpenCode** to use your token in the environment configuration. + +## Custom Domain (Optional) + +To use a custom domain with your GitHub Pages deployment: + +1. Add a `CNAME` file to your build output with your domain name +2. Configure DNS settings at your domain provider: + - Add a CNAME record pointing to `YOUR_USERNAME.github.io` +3. Enable HTTPS in GitHub Pages settings + +## Environment Variables + +Create a `.env.local` file in your repository root with necessary configuration: + +```env +# GitHub Configuration +GITHUB_TOKEN=your_personal_access_token_here + +# Optional: API Keys for AI providers +ANTHROPIC_API_KEY=your_anthropic_key +OPENAI_API_KEY=your_openai_key + +# Optional: Custom configuration +OPENCODE_BASE_URL=https://your-username.github.io/opencode +``` + +## Working with Multiple Repositories + +Once your OpenCode instance is deployed: + +1. **Clone your other repositories** locally: + ```bash + git clone https://github.com/YOUR_USERNAME/your-other-repo.git + cd your-other-repo + ``` + +2. **Run OpenCode** against those repositories: + ```bash + opencode + # or if running from source + bun dev /path/to/your-other-repo + ``` + +3. **Configure repository access** in OpenCode's settings to work across multiple repositories. + +## Updating Your Deployment + +To update your deployed version: + +1. **Sync with upstream** (optional): + ```bash + git remote add upstream https://github.com/anomalyco/opencode.git + git fetch upstream + git merge upstream/dev + ``` + +2. **Make your changes** and commit: + ```bash + git add . + git commit -m "Update deployment configuration" + ``` + +3. **Push to GitHub**: + ```bash + git push origin main + ``` + + The GitHub Actions workflow will automatically build and deploy your changes. + +## Troubleshooting + +### Build Failures + +- **Issue**: Build fails with dependency errors + - **Solution**: Clear cache and reinstall: `rm -rf node_modules bun.lock && bun install` + +- **Issue**: GitHub Actions workflow fails + - **Solution**: Check the Actions tab for detailed logs and ensure all secrets are configured + +### Access Issues + +- **Issue**: Cannot access other repositories + - **Solution**: Verify your Personal Access Token has the correct scopes and hasn't expired + +- **Issue**: 404 errors on GitHub Pages + - **Solution**: Check that the base path in your configuration matches your repository name + +### Performance Issues + +- **Issue**: Slow loading or timeouts + - **Solution**: Consider using a different hosting platform (Vercel, Netlify) for better performance, or optimize build output + +## Alternative Hosting Options + +While GitHub Pages is convenient, you may also consider: + +- **Vercel**: Better performance and automatic deployments +- **Netlify**: Similar to Vercel with additional features +- **Cloudflare Pages**: Fast global CDN +- **Self-hosted**: VPS or dedicated server for full control + +Each has its own advantages depending on your needs. + +## Security Considerations + +- Never commit sensitive tokens or API keys to your repository +- Use GitHub Secrets for sensitive configuration +- Regularly rotate your Personal Access Tokens +- Review and limit repository access permissions +- Enable branch protection rules on your main/dev branches + +## Getting Help + +- Check the [OpenCode documentation](https://opencode.ai/docs) +- Visit the [GitHub repository](https://github.com/anomalyco/opencode) +- Join the [Discord community](https://discord.gg/opencode) +- Review [contributing guidelines](./CONTRIBUTING.md) + +## License + +OpenCode is released under the MIT License. See [LICENSE](./LICENSE) for details. diff --git a/README.md b/README.md index 671a9072bf8..14429064ee9 100644 --- a/README.md +++ b/README.md @@ -110,6 +110,10 @@ Learn more about [agents](https://opencode.ai/docs/agents). For more info on how to configure OpenCode, [**head over to our docs**](https://opencode.ai/docs). +### Self-Hosting + +Want to host your own version of OpenCode on GitHub Pages? Check out our [**GitHub Pages hosting guide**](./GITHUB_PAGES_HOSTING.md) for detailed instructions on setting up your own instance. + ### Contributing If you're interested in contributing to OpenCode, please read our [contributing docs](./CONTRIBUTING.md) before submitting a pull request. From 657ed3b7416899e70a9b00f8453c411a3f86ad03 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Feb 2026 18:45:13 +0000 Subject: [PATCH 3/4] Clarify branch strategy and improve consistency in hosting guide Co-authored-by: Caleb-Lite <175520785+Caleb-Lite@users.noreply.github.com> --- GITHUB_PAGES_HOSTING.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/GITHUB_PAGES_HOSTING.md b/GITHUB_PAGES_HOSTING.md index 08394490036..652f5f8f58a 100644 --- a/GITHUB_PAGES_HOSTING.md +++ b/GITHUB_PAGES_HOSTING.md @@ -28,6 +28,8 @@ Before you begin, ensure you have: cd opencode ``` + > **Note**: The default branch for OpenCode is `dev`. Make sure you're working on the appropriate branch for your deployment. + 3. **Install dependencies**: ```bash bun install @@ -62,8 +64,7 @@ If you want to host the OpenCode documentation on GitHub Pages: on: push: branches: - - main - - dev + - dev # or main, depending on your default branch workflow_dispatch: permissions: @@ -207,11 +208,11 @@ Once your OpenCode instance is deployed: To update your deployed version: -1. **Sync with upstream** (optional): +1. **Sync with upstream** (optional, to get latest changes from the original repository): ```bash git remote add upstream https://github.com/anomalyco/opencode.git git fetch upstream - git merge upstream/dev + git merge upstream/dev # The default branch for OpenCode is 'dev' ``` 2. **Make your changes** and commit: @@ -220,9 +221,9 @@ To update your deployed version: git commit -m "Update deployment configuration" ``` -3. **Push to GitHub**: +3. **Push to GitHub** (to your default branch): ```bash - git push origin main + git push origin dev # or 'main' if that's your default branch ``` The GitHub Actions workflow will automatically build and deploy your changes. From b4abd9537742fac677d81d6065c50e17abe2a460 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 4 Feb 2026 18:45:49 +0000 Subject: [PATCH 4/4] Update Discord link to use official redirect URL Co-authored-by: Caleb-Lite <175520785+Caleb-Lite@users.noreply.github.com> --- GITHUB_PAGES_HOSTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GITHUB_PAGES_HOSTING.md b/GITHUB_PAGES_HOSTING.md index 652f5f8f58a..17f82bcff02 100644 --- a/GITHUB_PAGES_HOSTING.md +++ b/GITHUB_PAGES_HOSTING.md @@ -274,7 +274,7 @@ Each has its own advantages depending on your needs. - Check the [OpenCode documentation](https://opencode.ai/docs) - Visit the [GitHub repository](https://github.com/anomalyco/opencode) -- Join the [Discord community](https://discord.gg/opencode) +- Join the [Discord community](https://opencode.ai/discord) - Review [contributing guidelines](./CONTRIBUTING.md) ## License