Deploy BAX Sites to GitHub Pages - Easy Guide

GitHub Pages Deployment

BAX includes a ready-to-use GitHub Actions workflow for automatic deployment to GitHub Pages. This means your site builds and deploys automatically every time you push changes to your repository.

GitHub Pages is free, fast, and reliable. It's perfect for hosting static sites generated by BAX.

Step 1 - Enable Workflow

BAX comes with a workflow example file. You need to rename it to activate it:

mv .github/workflows/deploy.yml.example .github/workflows/deploy.yml

This workflow file tells GitHub Actions to:

• Checkout your code
• Make bax.sh executable
• Build your site with BAX
• Deploy the public folder to GitHub Pages

Workflow File Contents

Here's what the workflow does:

name: Deploy to GitHub Pages

on:

  push:

    branches: [ main, master ]

  workflow_dispatch:

jobs:

  build:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - name: Build with BAX

        run: |

          chmod +x bax.sh

          ./bax.sh

      - name: Upload artifact

        uses: actions/upload-pages-artifact@v3

        with:

          path: public/

  deploy:

    needs: build

    runs-on: ubuntu-latest

    permissions:

      pages: write

      id-token: write

    environment:

      name: github-pages

      url: ${{ steps.deployment.outputs.page_url }}

    steps:

      - name: Deploy to GitHub Pages

        id: deployment

        uses: actions/deploy-pages@v4

Step 2 - Push to GitHub

Now you need to push your code to GitHub:

git add .

git commit -m "Add BAX site with GitHub Pages deployment"

git push origin main

GitHub Actions will automatically trigger the workflow and build your site.

Step 3 - Enable GitHub Pages

After pushing, you need to enable GitHub Pages:

Via Repository Settings

1. Go to your repository on GitHub
2. Click Settings
3. Click Pages in the left sidebar
4. Under Source, select "GitHub Actions"
5. Wait for the deployment to complete

Via Workflow

Your site will be deployed automatically. The URL will be:

https://username.github.io/repository-name/

Custom Domain Setup

Want a custom domain for your BAX site?

Step 1 - Add Domain

Go to Settings → Pages and enter your custom domain.

Step 2 - Update DNS

Add these DNS records:

• A Record to GitHub Pages IP: 185.199.108.153
• CNAME to your GitHub Pages URL

Step 3 - Configure BAX

Update config.zet with your custom URL:

SITE_URL:https://yourdomain.com

Add a CNAME file:

echo yourdomain.com > public/CNAME

Step 4 - Verify Deployment

Check if your site is live:

Check Actions

• Go to Actions tab
• Look for your workflow run
• Wait for "Deploy to GitHub Pages" to complete

Check Pages

• Go to Settings → Pages
• Look for "Your site is published at..."
• Click the link to visit your site

Check Output

If you see your BAX site, deployment was successful

Troubleshooting

Workflow Not Running

• Check your main branch name (main or master)
• Make sure deploy.yml is in .github/workflows/
• Check GitHub Actions tab for errors

Build Fails

• Check bax.sh has correct permissions
• Check config.zet is valid
• Check data folder has .zet files
• Check pages folder has .zet files

Site Not Showing

• Check GitHub Pages settings
• Wait 1-2 minutes for deployment
• Check Actions tab for completion
• Check Pages URL is correct

Custom Domain Issues

• Check DNS propagation (24-48 hours)
• Check CNAME file exists
• Check config.zet SITE_URL matches

Best Practices

Before Deploying

• Test locally with bax.bat or bax.sh
• Check all links work
• Verify images load
• Test on different devices

Version Control

• Commit regularly
• Use meaningful commit messages
• Consider using branches
• Tag releases

Documentation

• Add README.md
• Include setup instructions
• Document your deployment process

Advanced Deployment Options

Multiple Branches

Deploy different versions from different branches:

on:

  push:

    branches:

      - main        # Production

      - develop     # Staging

Custom Build Command

Use different build commands:

- name: Build with BAX

  run: |

    chmod +x bax.sh

    ./bax.sh --production

Environment Variables

Use GitHub Secrets for sensitive data:

- name: Build with BAX

  env:

    SITE_URL: ${{ secrets.SITE_URL }}

  run: |

    ./bax.sh

Alternative Deployment Methods

Manual Deployment

• Build locally with bax.bat or bax.sh
• Copy public folder to GitHub
• Commit and push

Other Hosting

BAX works with any static hosting:

• Netlify
• Vercel
• Cloudflare Pages
• Surge.sh
• Any web hosting

Quick Reference

Commands

git clone https://github.com/mesinkasir/bax.git

cd bax

mv .github/workflows/deploy.yml.example .github/workflows/deploy.yml

git add .

git commit -m "Initial commit"

git push origin main

URL

https://username.github.io/repository-name/

"Automation is the key to efficient deployment. Let GitHub Actions handle the build and deploy process for you."