PocketStack

Add one GitHub Action and get a static, shareable preview for every browser-compatible Docker Compose pull request.

Open a PR → check every service → share the static preview.
_{Unsupported containers stay explicit and never masquerade as a working preview.}

PocketStack checks every active Compose service, maps compatible services to browser adapters, generates static output, deploys it to a stable Cloudflare Pages URL, and updates one pull-request comment on every push.

Important

PocketStack does not run arbitrary containers. If any active service needs Docker, Linux networking, a privileged process, or another unsupported runtime, the Action blocks the app deployment and publishes a compatibility report that says exactly why.

See the workflow · Set up PR previews · Compatibility matrix

Add the Action

Create .github/workflows/pocketstack.yml:

name: PocketStack Preview
on:
  pull_request:
    types: [opened, synchronize, reopened, closed]

permissions:
  contents: read
  pull-requests: write

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: ramazankara/pocketstack@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          compose-file: compose.yaml
          cloudflare-project: my-app-previews
          cloudflare-account-id: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}

The Action checks out the PR and builds its trusted PocketStack CLI itself; the workflow does not need a separate checkout or install step. Create the Cloudflare Pages Direct Upload project and add the two repository secrets once. The PR preview guide covers the exact setup, permissions, lifecycle, and security model.

What a pull request receives

Result	Check	Stable PR URL
Every service has a browser adapter	Passes	Working static app preview
Some services are compatible	Fails	Static compatibility report; no app preview
No services are compatible or analysis fails	Fails	Static blocker/error report; no app preview
PR comes from a fork or Dependabot	Reflects compatibility	No deployment or comment; secrets stay unavailable
PR closes	Passes after cleanup	Static closed-preview tombstone

The job summary is always written. For same-repository PRs, one sticky comment is created and updated instead of adding a new comment on every commit.

Three working examples

These recognizable apps exercise the same adapters and generation path as PR previews:

Application	Compose services	Browser adapters
Pocket Supply storefront	Vite storefront + fixture API	frontend, mock-http
Northstar sprint board	React board + Postgres seed	frontend, postgres-pglite
Clearview analytics	nginx static site	static-web

The storefront includes search, cart, quantities, and checkout; the sprint board supports issue creation, filtering, drag-and-drop, and keyboard moves; the analytics dashboard includes date ranges, SVG chart tooltips, and a sortable table.

Compatibility is the product boundary

PocketStack has six browser adapters:

• static-web — static nginx, Apache, or Caddy document roots;
• frontend — Node/Bun source running in WebContainer;
• mock-http — OpenAPI routes and JSON fixtures;
• postgres-pglite — Postgres-shaped demos using PGlite;
• sqlite — seeded SQLite databases;
• wasi — prebuilt WebAssembly System Interface modules.

A project generates only when every active service maps to one of these adapters. Arbitrary images, Dockerfile builds, Redis, opaque volumes, privileged containers, and real container networking do not silently fall back to a hosted runner. See adapters and the conversion guide.

Use the CLI locally

The GitHub Action is the shortest path to PR previews. The CLI exposes the same analyzer and generator for local use:

# Explain every service mapping and blocker.
pocketstack analyze -f compose.yaml

# Generate only when the whole active stack is browser-compatible.
pocketstack demo -f compose.yaml -o pocketstack-demo

Download a binary from GitHub Releases or follow installation. Generated demos are plain static files. Some adapters require COOP/COEP headers; PocketStack emits the host configuration when needed.

Security model

The preview workflow uses pull_request, never pull_request_target. It does not start Docker or execute package scripts from the PR in the GitHub runner. The analyzer confines Compose files, mounts, environment files, and labeled assets to the checked-out repository and rejects symlink escapes. Fork and Dependabot PRs do not receive Cloudflare credentials or a writable comment token.

For details, read PR preview security and SECURITY.md.

Documentation and development

• Getting started
• CLI reference
• Hosting and headers
• Architecture
• Contributing

Licensed under MIT.