CI/CD Integration

pageflare is designed to work in non-interactive environments. This page covers how to integrate it into your CI/CD pipeline.

Key Flags for CI

--no-progress

Disables the live progress spinners that clutter CI logs:

pageflare dist/ --output dist/ --no-progress

Auto-detection: When stdout is not connected to a terminal (i.e., output is piped or redirected), pageflare automatically suppresses spinners. In most CI environments this means you do not need the flag at all — it is provided for cases where auto-detection does not work as expected.

--json

Outputs a machine-readable JSON manifest instead of the human-readable summary table. Useful for parsing results, generating reports, or failing the build based on specific criteria:

pageflare dist/ --output dist/ --json > pageflare-report.json

--log <LEVEL>

Log messages go to stderr; the JSON/summary output goes to stdout. In CI you typically want warn (the default) or error to keep logs clean:

pageflare dist/ --output dist/ --log error

License in CI

Pro features require a valid license. In CI environments use the PAGEFLARE_LICENSE environment variable — this avoids storing the license token in the filesystem and works across all CI providers.

export PAGEFLARE_LICENSE=your-license-token
pageflare dist/ --output dist/

License resolution order (highest to lowest priority):

1. PAGEFLARE_LICENSE environment variable
2. License file at ~/.config/pageflare/license.json
3. Free tier (no license)

Store the token as a secret in your CI provider and inject it as an environment variable — never commit it to source control.

Exit Codes

Code	Meaning
0	Success — all files processed without errors
1	One or more files encountered errors during processing

Use the exit code to fail your pipeline if pageflare reports errors:

pageflare dist/ --output dist/ || exit 1

In most CI environments (GitHub Actions, GitLab CI) a non-zero exit code automatically fails the step, so this is the default behavior.

GitHub Actions

Official Action (recommended)

The easiest way to use pageflare in GitHub Actions — one line, no install needed:

- uses: getappz/pageflare-cli@v1

Auto-detects your framework and build output directory. Pass options via args:

- uses: getappz/pageflare-cli@v1
  with:
    args: "dist -o optimized --platform vercel"
  env:
    PAGEFLARE_LICENSE: ${{ secrets.PAGEFLARE_LICENSE }}

Pin a specific version:

- uses: getappz/pageflare-cli@v1
  with:
    version: "0.4.0"

Full Workflow Example

name: Build and Optimize

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci

      - name: Build site
        run: npm run build

      - name: Optimize
        uses: getappz/pageflare-cli@v1
        env:
          PAGEFLARE_LICENSE: ${{ secrets.PAGEFLARE_LICENSE }}

      - name: Deploy
        # Your deployment step here
        run: echo "Deploy optimized output to your host"

With JSON Report

      - name: Optimize site
        uses: getappz/pageflare-cli@v1
        with:
          args: "dist --json > pageflare-report.json"
        env:
          PAGEFLARE_LICENSE: ${{ secrets.PAGEFLARE_LICENSE }}

      - name: Upload optimization report
        uses: actions/upload-artifact@v4
        with:
          name: pageflare-report
          path: pageflare-report.json

Manual Install (alternative)

If you prefer to install the binary directly instead of using the action:

      - name: Install pageflare
        run: curl -fsSL https://get.appz.dev/pageflare/install.sh | sh

      - name: Optimize site
        env:
          PAGEFLARE_LICENSE: ${{ secrets.PAGEFLARE_LICENSE }}
        run: pageflare dist/ --output dist/

GitLab CI

Basic Pipeline

stages:
  - build
  - optimize
  - deploy

build:
  stage: build
  image: node:20-alpine
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

optimize:
  stage: optimize
  image: alpine:latest
  dependencies:
    - build
  script:
    - curl -fsSL https://get.appz.dev/pageflare/install.sh | sh
    - pageflare dist/ --output dist/ --no-progress
  variables:
    PAGEFLARE_LICENSE: $PAGEFLARE_LICENSE  # Set in CI/CD > Variables
  artifacts:
    paths:
      - dist/

deploy:
  stage: deploy
  dependencies:
    - optimize
  script:
    - echo "Deploy dist/ to your host"
  only:
    - main

Store PAGEFLARE_LICENSE in Settings > CI/CD > Variables with the “Masked” option enabled to keep it out of job logs.

Docker

Use the official Docker image pageflare/cli to avoid installing the binary altogether. This is useful for CI systems that support container-based steps.

GitHub Actions (container step)

      - name: Optimize site
        uses: docker://pageflare/cli:latest
        with:
          args: dist/ --in-place --no-progress
        env:
          PAGEFLARE_LICENSE: ${{ secrets.PAGEFLARE_LICENSE }}

GitLab CI (image)

optimize:
  stage: optimize
  image: pageflare/cli:latest
  dependencies:
    - build
  script:
    - pageflare dist/ --in-place --no-progress
  variables:
    PAGEFLARE_LICENSE: $PAGEFLARE_LICENSE
  artifacts:
    paths:
      - dist/

Generic Docker

docker run --rm \
  -e PAGEFLARE_LICENSE="$PAGEFLARE_LICENSE" \
  -v "$(pwd)/dist:/site" \
  pageflare/cli /site --in-place --no-progress

Bitbucket Pipelines

pipelines:
  branches:
    main:
      - step:
          name: Build
          image: node:22-alpine
          caches:
            - node
          script:
            - npm ci
            - npm run build
          artifacts:
            - dist/**

      - step:
          name: Optimize
          image: alpine:latest
          script:
            - apk add --no-cache curl bash
            - curl -fsSL https://get.appz.dev/pageflare/install.sh | sh
            - ~/.pageflare/bin/pageflare dist/ --output dist/
          artifacts:
            - dist/**

      - step:
          name: Deploy
          script:
            - echo "Deploy dist/ to your host"

Store PAGEFLARE_LICENSE in Repository settings > Pipelines > Repository variables with the “Secured” checkbox enabled.

CircleCI

version: 2.1

jobs:
  build-and-optimize:
    docker:
      - image: cimg/node:22.0
    steps:
      - checkout
      - run: npm ci && npm run build
      - run:
          name: Install and run pageflare
          command: |
            curl -fsSL https://get.appz.dev/pageflare/install.sh | sh
            ~/.pageflare/bin/pageflare dist/ --output dist/
      - persist_to_workspace:
          root: .
          paths:
            - dist/

  deploy:
    docker:
      - image: cimg/base:stable
    steps:
      - attach_workspace:
          at: .
      - run: echo "Deploy dist/ to your host"

workflows:
  build-optimize-deploy:
    jobs:
      - build-and-optimize
      - deploy:
          requires:
            - build-and-optimize
          filters:
            branches:
              only: main

Store PAGEFLARE_LICENSE in Project Settings > Environment Variables.

AWS CodeBuild

version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 22
    commands:
      - npm ci
  build:
    commands:
      - npm run build
  post_build:
    commands:
      - curl -fsSL https://get.appz.dev/pageflare/install.sh | sh
      - ~/.pageflare/bin/pageflare dist/ --output dist/

artifacts:
  files:
    - dist/**

Azure Pipelines

trigger:
  branches:
    include:
      - main

pool:
  vmImage: "ubuntu-latest"

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: "22.x"

  - script: npm ci && npm run build
    displayName: "Build"

  - script: |
      curl -fsSL https://get.appz.dev/pageflare/install.sh | sh
      ~/.pageflare/bin/pageflare dist/ --output dist/
    displayName: "Optimize with pageflare"
    env:
      PAGEFLARE_LICENSE: $(PAGEFLARE_LICENSE)

Store PAGEFLARE_LICENSE in Pipelines > Library > Variable groups or as a pipeline variable with the lock icon.

Other CI Systems

The pattern is the same regardless of CI provider:

1. Build your static site normally
2. Set PAGEFLARE_LICENSE as a secret environment variable
3. Install and run pageflare
4. Deploy the output directory

# Generic CI shell script
set -e

npm run build
curl -fsSL https://get.appz.dev/pageflare/install.sh | sh
~/.pageflare/bin/pageflare dist/ --output dist/

Parsing JSON Output

The --json flag writes a structured manifest to stdout. Example structure:

{
  "summary": {
    "total": 42,
    "optimized": 38,
    "unchanged": 4,
    "errors": 0,
    "bytes_before": 390144,
    "bytes_after": 240640,
    "elapsed_ms": 1234
  },
  "files": [
    {
      "path": "index.html",
      "status": "optimized",
      "bytes_before": 12800,
      "bytes_after": 9200
    }
  ]
}

Use a tool like jq to extract specific values:

pageflare dist/ --output dist/ --json | jq '.summary.errors'
# Fail the build if any files errored
pageflare dist/ --output dist/ --json | jq 'if .summary.errors > 0 then error else . end'