Getting Started with Previewops

Previewops automatically deploys pull-request previews to your cloud account. Comment /deploy-previewops on any PR and the bot builds your Docker image, deploys it, and replies with the live URL — all within minutes.

How it works

  1. You (or a teammate) comment /deploy-previewops on a pull request.
  2. Previewops builds a Docker image from the PR branch (via Cloud Build, SSH, or your provider's native build, depending on configuration).
  3. The image is deployed to your chosen cloud provider (Cloud Run, Fly.io, AWS Lightsail, etc.).
  4. Previewops posts a comment on the PR with the preview URL.
  5. When the PR is merged or closed, Previewops deletes the preview automatically.
  6. Previews also expire automatically after their TTL (default: 24 hours).

Prerequisites

  1. GitHub App installed on your organisation or repository. Install Previewops →

  2. Cloud credentials stored (required for Free and Premium BYOC plans). See credentials.md.

    Free BYOC: only public repositories are supported. Private repo support requires Premium BYOC.

  3. A Dockerfile in your repository root (or configured via .previewops.yaml). If your Dockerfile is not in the repo root, you will need to set the path in .previewops.yaml before your first deploy.

    Previewops builds and runs your container as-is. A few requirements:

    • The container must listen on a port (Previewops detects it automatically, or you can pin it via port: in .previewops.yaml).
    • The container must start quickly — Previewops polls for readiness after deploy; a slow cold start will delay the preview URL appearing on the PR.
    • Run as a non-root user where possible (required by some providers, e.g. Cloud Run).

    A minimal production-ready multi-stage Dockerfile looks like this:

    # ── Build stage ──────────────────────────────────────────────────────────
FROM node:22-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# ── Runtime stage ────────────────────────────────────────────────────────
FROM node:22-alpine AS runtime

# Non-root user (required by Cloud Run; best practice everywhere)
RUN addgroup -S app && adduser -S app -G app

WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package.json ./

USER app

ENV NODE_ENV=production
ENV PORT=8080
EXPOSE 8080

CMD ["node", "dist/index.js"]

    Adjust the build commands, copied paths, and base image for your language/framework. For non-Node stacks (Python, Go, Ruby, etc.) the same multi-stage pattern applies — compile/install in a builder stage, copy only the artefacts into a slim runtime image.

Your first deploy

Step 1 — Install the GitHub App

Go to the Previewops GitHub App page and install it on your organisation or the specific repositories you want to enable.

After installation, sign in to the dashboard with GitHub. If you belong to multiple organisations that have Previewops installed, you'll be prompted to choose which org's dashboard to access.

Step 2 — Store your cloud credentials (BYOC plans)

If you are on the Free or Premium BYOC plan, you need to add your cloud provider credentials before your first deploy. Click Credentials in the left sidebar, or see credentials.md for a step-by-step walkthrough.

Pro, Enterprise, and Custom plan users can skip this step — Previewops handles the cloud account for you.

Step 3 — Open a pull request and deploy

Comment on any open PR in an enabled repository:

/deploy-previewops

Previewops will reply with a "Building Previewops environment…" comment on the PR, then update it with the live preview URL once the deploy completes (typically 2–5 minutes depending on build time).

Deploy status guide:

  • ✅ Live — the service deployed successfully. If the preview URL doesn't respond immediately, the app may still be starting up — wait 30–60 seconds and refresh.
  • ❌ Failed — a credential or configuration problem stopped the deploy. Expand the Show build logs section in the PR comment to see the error, or use the included Ask Claude / Ask ChatGPT / Open in Cursor links to get AI-assisted debugging help. Run /validate-previewops to check your credentials and configuration.
  • ✅ Live (app may still be starting) — the service deployed successfully but didn't respond to a health check in time. The preview URL is usable — try it directly.

Step 4 — Configure per-repo settings (required if Dockerfile is not in root)

Add a .previewops.yaml file to the root of your repository to customise TTL, concurrency, the Dockerfile path, and more. See configuration.md for all available options.

Next steps