Deploy to GitHub Pages

GitHub Pages provides free hosting for static sites directly from your GitHub repositories. Opal Editor uses Git-based deployment to push your built sites to GitHub Pages.

Prerequisites

Before deploying to GitHub Pages:

A GitHub account
A GitHub repository for hosting your site
GitHub authentication (Personal Access Token or OAuth)
A completed build ready for deployment

Authentication Setup

Opal Editor supports multiple GitHub authentication methods:

Personal Access Token (Recommended)

Create a Personal Access Token

Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
Click “Generate new token (classic)”
Give it a descriptive name (e.g., “Opal Editor”)
Select scopes:
- repo (full control of private repositories)
- public_repo (for public repositories only)
Click “Generate token”
Copy the token immediately (it won’t be shown again)

Add to Opal Editor

Create a new GitHub API authentication in Opal Editor and paste your token.

Store your Personal Access Token securely. It provides access to your repositories.

OAuth

Alternative authentication methods:

OAuth: Browser-based authentication flow
Device Flow: CLI-friendly authentication without browser

Destination Configuration

Configure your GitHub Pages deployment:

{
  "remoteAuthId": "your-auth-id",
  "label": "My GitHub Pages Site",
  "meta": {
    "repository": "username/repo-name",
    "branch": "gh-pages",
    "baseUrl": "/"
  }
}

Configuration Fields

repository (required): GitHub repository in format owner/repo or full URL
- Examples: username/my-site or https://github.com/username/my-site
- Automatically normalized to owner/repo format
branch (required): Branch for deployment (default: gh-pages)
- Common choices: gh-pages, main, master
baseUrl (required): Base URL path for your site
- Use / for user/org pages (username.github.io)
- Use /repo-name/ for project pages

For project repositories, the baseUrl should match your repository name: /repo-name/

Deployment Process

GitHub Pages deployment uses Git to push your built site:

Configure repository

Set up your deployment:

Specify repository (created if doesn’t exist)
Choose deployment branch
Set base URL for correct link paths

Build your site

Complete a build in Opal Editor:

Files are processed and built
HTML is generated
Assets are prepared

Deploy via Git

Deployment process:

Temporary Git repository is created
Built files are committed
Changes are force-pushed to specified branch
Repository is cleaned up

GitHub Pages activation

GitHub automatically:

Detects the new commit
Builds and deploys your site
Makes it available at the Pages URL

Access your site

Your site is live at:

User/Org pages: https://username.github.io
Project pages: https://username.github.io/repo-name

How It Works

The GitHub deployment process (RemoteAuthGithubAgent):

Repository Validation: Verifies repository exists or creates it
Git Initialization: Creates a temporary Git repository
Commit Creation: Commits all built files
Remote Push: Force-pushes to the specified branch
URL Generation: Returns the GitHub Pages URL
Cleanup: Removes temporary Git repository

Git-Based Deployment

Unlike other platforms, GitHub Pages uses Git:

// Deployment flow:
GitRepo.GHPagesRepo() // Create temp repo
GitPlaybook.initialCommit() // Commit files
GitPlaybook.pushRemoteAuth() // Push to GitHub
repo.dispose() // Cleanup

Key features:

Force push for clean deployments
Full file replacement each time
No merge conflicts
Complete deployment history

URL Rewriting

For non-root base URLs, Opal Editor automatically:

Rewrites absolute URLs in HTML files
Updates links to include base URL
Ensures assets load correctly
Handles script and style references

Example:

<!-- Before rewriting (baseUrl: /my-site/) -->
<link href="/style.css">

<!-- After rewriting -->
<link href="/my-site/style.css">

Repository Types

User/Organization Pages

For username.github.io repositories:

{
  "repository": "username/username.github.io",
  "branch": "main",
  "baseUrl": "/"
}

Must be named username.github.io
Deploy to main branch (or configure in settings)
Base URL is always /
Site URL: https://username.github.io

Project Pages

For project repositories:

{
  "repository": "username/my-project",
  "branch": "gh-pages",
  "baseUrl": "/my-project/"
}

Any repository name
Typically use gh-pages branch
Base URL must match repo name
Site URL: https://username.github.io/my-project

Features

Free Hosting

GitHub Pages is completely free:

Unlimited public repositories
1GB storage limit
100GB bandwidth per month
Custom domain support

Automatic HTTPS

All GitHub Pages sites include:

Free SSL certificates
HTTPS enforced (optional)
Automatic certificate renewal

Custom Domains

Configure custom domains:

Add CNAME file to your repository
Configure DNS records
Enable HTTPS in repository settings

Deployment History

Git-based deployment provides:

Complete commit history
Ability to view previous versions
Revert to earlier deployments
Full audit trail

Troubleshooting

Repository Not Found

If “Repository not found”:

Verify repository name format: owner/repo
Check your token has access to the repository
Ensure repository exists (or will be created)
Confirm repository is not private (unless token has repo scope)

Solution: Verify the repository name and your access permissions.

Authentication Failures

If Git push fails:

Verify Personal Access Token is valid
Check token has repo or public_repo scope
Ensure token hasn’t expired
Try regenerating the token

404 After Deployment

If site shows 404 after deployment:

Enable GitHub Pages in repository settings
Select correct branch (gh-pages)
Wait a few minutes for GitHub to build
Check repository visibility (public vs private)
Verify branch contains index.html

Wrong Base URL

If styles/assets don’t load:

Check baseUrl matches repository name
For user pages, use /
For project pages, use /repo-name/
Verify HTML contains correct URLs

Force Push Issues

Deployment uses force push:

Previous branch history is overwritten
Don’t use the same branch for development
Use dedicated deployment branch (gh-pages)
Never force push to main if used for source code

Best Practices

Use dedicated branch: Deploy to gh-pages, keep code in main
Set correct base URL: Match repository name for project pages
Enable HTTPS: Configure in repository settings
Add custom domain: Use CNAME for professional URLs
Monitor deployment: Check Actions tab for GitHub’s build process
Test locally: Ensure build completes before deploying

Advanced Configuration

Custom Domain Setup

Add a custom domain:

Add CNAME file

Include a CNAME file in your build output:

www.yourdomain.com

Configure DNS

Add DNS records at your domain provider:

CNAME  www  username.github.io.

Enable HTTPS

In repository settings > Pages:

Verify custom domain
Enable “Enforce HTTPS”

Jekyll Override

Disable Jekyll processing: Add a .nojekyll file to your build output to prevent GitHub from processing your site with Jekyll.

404 Page

Create a custom 404 page: Add 404.html to your build output. GitHub Pages will serve it for missing pages.

Deployment Workflow

For automated deployments, combine with:

GitHub Actions for CI/CD
Webhook triggers
Scheduled deployments

Performance Optimization

CDN

GitHub Pages uses Fastly CDN:

Global distribution
Edge caching
Fast content delivery

Caching

Optimize caching:

Use versioned asset filenames
Set appropriate cache headers
Leverage browser caching

Get Started

Core Features

Publishing

Advanced

Deploy to GitHub Pages

Prerequisites

Authentication Setup

Personal Access Token (Recommended)

OAuth

Destination Configuration

Configuration Fields

Deployment Process

How It Works

Git-Based Deployment

URL Rewriting

Repository Types

User/Organization Pages

Project Pages

Features

Free Hosting

Automatic HTTPS

Custom Domains

Deployment History

Troubleshooting

Repository Not Found

Authentication Failures

404 After Deployment

Wrong Base URL

Force Push Issues

Best Practices

Advanced Configuration

Custom Domain Setup

Jekyll Override

404 Page

Deployment Workflow

Performance Optimization

CDN

Caching

Build docs developers (and LLMs) love

Get Started

Core Features

Publishing

Advanced

​Prerequisites

​Authentication Setup

​Personal Access Token (Recommended)

​OAuth

​Destination Configuration

​Configuration Fields

​Deployment Process

​How It Works

​Git-Based Deployment

​URL Rewriting

​Repository Types

​User/Organization Pages

​Project Pages

​Features

​Free Hosting

​Automatic HTTPS

​Custom Domains

​Deployment History

​Troubleshooting

​Repository Not Found

​Authentication Failures

​404 After Deployment

​Wrong Base URL

​Force Push Issues

​Best Practices

​Advanced Configuration

​Custom Domain Setup

​Jekyll Override

​404 Page

​Deployment Workflow

​Performance Optimization

​CDN

​Caching

​Related Resources

Build docs developers (and LLMs) love

Prerequisites

Authentication Setup

Personal Access Token (Recommended)

OAuth

Destination Configuration

Configuration Fields

Deployment Process

How It Works

Git-Based Deployment

URL Rewriting

Repository Types

User/Organization Pages

Project Pages

Features

Free Hosting

Automatic HTTPS

Custom Domains

Deployment History

Troubleshooting

Repository Not Found

Authentication Failures

404 After Deployment

Wrong Base URL

Force Push Issues

Best Practices

Advanced Configuration

Custom Domain Setup

Jekyll Override

404 Page

Deployment Workflow

Performance Optimization

CDN

Caching

Related Resources