GitHub Pages

GitHub Pages serves static sites directly from a repository. The default build pipeline is limited — it runs Jekyll with no support for post-build hooks. To use pageflare, use a custom GitHub Actions workflow instead.

How It Works

Replace the default GitHub Pages build with a custom workflow that builds your site, runs pageflare, and deploys the optimized output.

Step 1 — Enable GitHub Actions Deployment

1. Go to your repository Settings > Pages.
2. Under Build and deployment, set Source to GitHub Actions.
3. This disables the default Jekyll build and lets your workflow handle deployment.

Step 2 — Create the Workflow

Create .github/workflows/pages.yml:

.github/workflows/pages.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build site
        run: npm run build

      - name: Optimize with pageflare
        uses: getappz/pageflare-cli@v1
        with:
          args: "dist/ --in-place"

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}
    steps:
      - name: Deploy
        id: deploy
        uses: actions/deploy-pages@v4

Replace dist/ with your framework’s output directory (_site/ for Jekyll, public/ for Hugo, build/ for Docusaurus, etc.).

Jekyll Example

.github/workflows/pages.yml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true

      - name: Build Jekyll
        run: bundle exec jekyll build

      - name: Optimize with pageflare
        uses: getappz/pageflare-cli@v1
        with:
          args: "_site/ --in-place"

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: _site/

Hugo Example

.github/workflows/pages.yml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3

      - name: Build Hugo
        run: hugo --minify

      - name: Optimize with pageflare
        uses: getappz/pageflare-cli@v1
        with:
          args: "public/ --in-place"

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: public/

Step 3 — Pro License

To use Pro features, add your license as a repository secret:

1. Go to Settings > Secrets and variables > Actions.
2. Add a secret named PAGEFLARE_LICENSE with your license key.
3. Reference it in the workflow:

      - name: Optimize with pageflare
        uses: getappz/pageflare-cli@v1
        with:
          args: "dist/ --in-place"
        env:
          PAGEFLARE_LICENSE: ${{ secrets.PAGEFLARE_LICENSE }}

Step 4 — Verify

After pushing, go to Actions in your repository. The workflow should run, and the deploy step should show a URL. Check the build logs for the pageflare summary:

  Done  145.2 KB saved (38.1%)  1.2s
  Files  42 total, 38 optimized, 4 unchanged, 0 errors

Framework Output Directories

Framework	Output directory
Jekyll	_site/
Hugo	public/
Astro	dist/
Eleventy	_site/
Vite / SvelteKit	dist/
Docusaurus	build/
MkDocs	site/
Next.js static export	out/

Troubleshooting

Workflow not triggering Make sure the Pages source is set to GitHub Actions (not “Deploy from a branch”). Check that the workflow file is on the main branch.

404 after deployment Verify the path in upload-pages-artifact matches your framework’s output directory. Check that the output contains an index.html.

Custom domain not working Add a CNAME file to your output directory with your custom domain. Most frameworks support this via configuration — check your framework’s GitHub Pages docs.