Deploy Jupyter notebooks as interactive JupyterLite sites on GitHub Pages with automatic branch deployments.

Create .github/workflows/deploy.yml in your repository:

name: Deploy JupyterLite on: push: branches: ['**'] # Deploy all branches permissions: contents: write jobs: deploy: uses: DurhamARC-Training/PythonCourse-jupyterlite/.github/workflows/deploy-jupyterlite.yml@main secrets: inherit

Optional: For immediate cleanup when branches are deleted, also create .github/workflows/cleanup.yml:

name: Cleanup Deleted Branch on: delete permissions: contents: write jobs: cleanup: uses: DurhamARC-Training/PythonCourse-jupyterlite/.github/workflows/cleanup-branch-deployment.yml@main secrets: inherit

Optional: Add a PR comment workflow for deployment previews on new PRs by creating .github/workflows/pr-comment.yml:

name: Add PR Deployment Comment on: pull_request: types: [opened] permissions: pull-requests: write jobs: comment: uses: DurhamARC-Training/PythonCourse-jupyterlite/.github/workflows/pr-comment-generation.yml@main

1. Go to Settings → Environments
2. If there is a ruleset for github-pages edit it.
3. Change Deployment branches and tags to No restriction

After the first workflow run:

1. Go to Settings → Pages
2. Source: Deploy from a branch
3. Branch: gh-pages / / (root)
4. Click Save

1. Repeat Step 2.

Done! Your notebooks are now deployed. The workflow automatically creates the gh-pages branch on first run.

• Zero-config deployment - works out of the box
• Branch deployments - preview changes at https://org.github.io/repo/branch/branch-name/
• Auto-cleanup - removes deployments when branches are deleted
• SEO protection - branch deployments blocked from search engines
• Auto-updates - improvements to template apply automatically
• No gh-pages setup - branch created automatically on first run

• Branch names with / are converted to - in URLs
• Non-main branches are protected from search engines via robots.txt and meta tags

Required:

• Jupyter notebooks (.ipynb files) anywhere in your repo

Optional:

• requirements.txt - Python packages for your notebooks

Example structure:

my-course/ ├── .github/workflows/deploy.yml ├── notebooks/*.ipynb ├── requirements.txt (optional) └── data/*.csv (optional) 

All parameters are optional with sensible defaults:

jobs: deploy: uses: DurhamARC-Training/PythonCourse-jupyterlite/.github/workflows/deploy-jupyterlite.yml@main with: python-version: '3.11' # Python version (default: 3.11) deploy-branches: true # Deploy non-main branches (default: true) cleanup-stale-branches: true # Auto-cleanup (default: true) template-repo: 'Org/CustomTemplate' # Custom template (default: this repo) secrets: inherit

Stale branch deployments are automatically removed on every push (enabled by default) in addition to the optional cleanup on branch deletion.

To disable:

jobs: deploy: uses: DurhamARC-Training/PythonCourse-jupyterlite/.github/workflows/deploy-jupyterlite.yml@main with: cleanup-stale-branches: false secrets: inherit

1. Enable GitHub Pages: Settings → Pages → Source: "Deploy from a branch" → Branch: "gh-pages" → Folder: "/ (root)"
2. Check workflow permissions: Settings → Actions → General → Workflow permissions: "Read and write permissions"
3. Wait a few minutes after first deployment for GitHub Pages to activate
4. Check Actions logs for errors

The workflow now automatically creates the gh-pages branch on first run. If you still see this error, it may be a transient issue - re-run the workflow. Otherwise raise an issue in the template repository.

• First deployment to any branch creates the gh-pages branch
• Wait 2-3 minutes for GitHub Pages to update
• Check that the branch deployment exists at: https://org.github.io/repo/branch/branch-name/