Configuration Reference

This document covers the active, user-facing fields in .previewops.yaml and selected non-secret operator defaults. If you are self-hosting, see Self-hosting for the complete infrastructure configuration.

.previewops.yaml

Place this file in the root of each repository you want to configure. All fields except version are optional, and version defaults to 1 when omitted.

# Configuration format version.
version: 1

# Maximum simultaneous preview environments for this repository.
# When the limit is reached, the oldest preview is evicted automatically.
# Your plan cap applies on top of this value, whichever is lower.
# Type: number  Range: 1–30  Standard default: 3
concurrency: 3

# TTL before the preview is automatically deleted.
# Type: number (hours)  Range: 1–720  Standard default: 24
ttlHours: 72

# Dockerfile path and build context, relative to the repository root.
# Absolute paths and parent-directory traversal (..) are not allowed.
# Type: string  Defaults: "Dockerfile" and "."
dockerfilePath: Dockerfile
buildContext: .

# HTTP port your container listens on.
# When omitted, Previewops reads the first integer EXPOSE instruction from the
# Dockerfile. It falls back to 8080 when no integer EXPOSE value is found.
# An explicit value must match an integer EXPOSE value in the Dockerfile.
# Type: number  Range: 1–65535  Optional
port: 3000

# Container resources. The accepted values and exact effect are provider-dependent.
# These examples are Cloud Run-compatible values.
# Type: string  Standard defaults: 512Mi and 1
memory: 256Mi
cpu: "0.5"

# Non-secret environment variables injected into the preview container.
# Quote values that YAML might otherwise parse as numbers or booleans.
# Type: map<string, string>  Default: {}
env:
  NODE_ENV: preview
  FEATURE_FLAG: "true"
  API_BASE_URL: https://api.staging.example.com

# Branches that automatically deploy when a push arrives and an open PR exists.
# No /deploy-previewops comment is needed.
# Type: string[]  Default: []
alwaysOn:
  - staging

# Deployment provider. See the supported-provider and credential references below.
# Type: string  Default: "cloud-run"
# Options: cloud-run fly hetzner docker-ssh render railway digitalocean
#          aws-lightsail aws-ecs azure-container-apps
provider: cloud-run

# Non-secret structural configuration for the selected provider.
# Type: object  Default: {}  (see the providerConfig reference below)
providerConfig: {}

Validation behavior: Previewops validates the complete file. If any validated value is invalid, it logs the validation failure and uses the complete default configuration rather than applying the remaining valid fields. Unknown keys are ignored. Path values may contain letters, numbers, ., _, -, and /, but cannot be absolute or contain .. segments.

Keep secrets out of env:. These values are committed to git in plaintext and are visible to anyone with repository access. Store secrets under Secrets & Environment Variables in the Previewops dashboard, or pass them through the workflow secrets: or env: configuration in CLI mode. GitHub Actions expressions are not interpolated inside .previewops.yaml. At deployment, values are applied in this order: repository env, stored dashboard secrets, then Preview DB values. Later sources overwrite matching keys. See Credentials, Databases, and Authentication.

Configure the application port with port, not env.PORT. Previewops resolves the deployment port and injects PORT for the container. Supplying a separate PORT value through repository or stored environment variables can produce provider-dependent behavior or a health-check mismatch.

Resource handling also varies by provider. Cloud Run uses the configured memory and cpu values directly; Fly ignores the CPU value; Azure derives memory from the CPU value; VM-backed providers primarily use their selected instance size; and other providers may ignore one or both fields.

providerConfig reference

Non-secret fields may be committed here. Keep access tokens, private keys, client secrets, and cloud secret keys in the dashboard credential store or your self-hosted environment.

* Required overall, but it may be supplied through the corresponding dashboard credential instead of providerConfig. The exact credential keys are listed in Credentials per provider.

AWS ECS creates a dedicated public HTTP Application Load Balancer for each preview; it does not require a shared listener or base domain. The current provider assigns executionRoleArn as both the ECS execution role and the application task role. Use a dedicated, least-privilege role and do not grant permissions that the preview application does not require.

QA testing: qa block

Controls /qa-previewops behavior for this repository. All fields are optional.

qa:
  # Controls Playwright draft generation for active QA Hub scenarios.
  # "auto" (default): follows the organization-level generate-drafts setting.
  # true: generates drafts when QA Hub access, LLM access, a preview URL, and
  #       active scenarios are all available.
  # false: never generates drafts. This overrides the command flag and org setting.
  generateDrafts: auto

  # Minimum impacted-scenario priority that marks the GitHub Check Run as
  # action_required: p0 (default), p1, p2, or none.
  scenarioImpactCheck: p0

  # Skip LLM analysis for this repository regardless of plan.
  # Equivalent to always passing --coverage-only. No AI credits are consumed.
  # Type: boolean  Default: false
  coverageOnly: false

  # Review the whole diff instead of one prompt-sized slice of it.
  #
  # By default the AI review reads the highest-priority slice that fits the token
  # budget — around 26 files on a large pull request. With this on, the reviewable
  # files are split across up to 3 passes and the findings are merged, so a defect
  # in a lower-priority file is still found.
  #
  # Costs one QA run either way: billing is per run, not per pass. Slower, and
  # more thorough. Off by default so nothing changes for you without asking.
  #
  # Can also be requested per run with /qa-previewops --full-diff. Setting false
  # here is an absolute deny — the flag will not override it.
  # Type: boolean  Default: false
  fullDiff: false

  # Maximum number of changed files sent to the LLM prompt.
  # Omit to use the platform default (40). Setting it here overrides that.
  # Type: integer  Default: 40  Max: 100
  maxFiles: 40

  # Maximum total patch characters across all files sent to the LLM.
  # Omit to use the platform default (80000). Setting it here overrides that —
  # a lower value means fewer files reach the model, so the review sees less.
  # Type: integer  Default: 80000  Min: 1000  Max: 200000
  maxTotalPatchChars: 80000

QA Hub is available only on supported managed plans; it is not part of Premium BYOC. The core /qa-previewops analysis remains usable according to your plan and configured LLM access. See QA testing.

Performance testing: performance block

Enables and configures load testing for preview environments. See Performance testing for command flags, plan limits, and result interpretation.

performance:
  # Automatically run a performance test after each successful deployment.
  enabled: false

  # Virtual users and timings. Plan limits still apply.
  vus: 10
  duration: 30s
  rampUp: 5s

  # Optional best-effort cap on aggregate requests per second.
  # targetTps: 100

  # Base path prepended to detected or configured endpoints.
  # apiBasePath: /api/v1

  # Service-level objectives. Violations are reported as warnings, not test failures.
  # The default maximum error rate is 0.05 even when this block is omitted.
  slo:
    p90: 400          # milliseconds; optional
    p95: 500          # milliseconds; optional
    p99: 1000         # milliseconds; optional
    errorRate: 0.05   # fraction

  # Explicit scenarios. When omitted, endpoints are detected from the PR diff.
  scenarios:
    - path: /users
      method: GET
    - path: /orders
      method: POST
      body: '{"item": "widget"}'
      headers:
        Content-Type: application/json

  # Trusted custom k6 script, relative to the repository root.
  # It controls its own VUs, timing, ramp, and throughput. Previewops injects only
  # TARGET_URL as __ENV.TARGET_URL. If the file is unavailable, generation is used.
  # scriptPath: k6/load-test.js

Run performance tests only against isolated, nonproduction previews that you are authorized to test. Requests—including POST, PUT, PATCH, and DELETE—may run repeatedly. Do not place credentials or customer data in scenario headers, bodies, or custom scripts.

Preview DB: previewDb block

Controls how the Preview DB add-on injects the per-PR branch connection string. The add-on must be active.

previewDb:
  # Environment variable that receives the branch connection string.
  # It must be 1–64 characters, start with an uppercase letter, and contain only
  # uppercase letters, digits, and underscores. Default: DATABASE_URL.
  # PREVIEW_DB_URL is always injected as a stable alias.
  envVar: DATABASE_URL

If envVar matches a key in repository env or stored dashboard secrets, Preview DB overwrites that value with the branch connection string and adds a warning to the PR dashboard comment. Choose another key if you need to preserve the existing value.

Monorepo: services array

For a repository with multiple Dockerfiles, add services. Top-level deployment fields act as defaults, and each service can override its own build and container settings.

version: 1

ttlHours: 24
provider: cloud-run

services:
  - name: web           # 1–20 lowercase letters, numbers, or hyphens
    dockerfilePath: apps/web/Dockerfile
    buildContext: apps/web
    port: 3000
    memory: 256Mi
    cpu: "0.5"
    env:
      NEXT_PUBLIC_API_URL: https://api.preview.example.com

  - name: api
    dockerfilePath: apps/api/Dockerfile
    buildContext: apps/api
    port: 8080
    memory: 128Mi
    env:
      LOG_LEVEL: debug

Preview names generally use prev-{owner}-{repo}-{name}-pr{pr}, subject to provider-specific naming and length limits, and all service URLs are posted together in one PR comment. Top-level settings such as ttlHours, concurrency, and provider apply to every service.

A service-level env map replaces the top-level env map rather than merging with it. Stored dashboard secrets and Preview DB values are applied afterward.

Selected operator environment variables

These variables configure a self-hosted Previewops service. They are not environment variables for the deployed preview application. See Self-hosting for the full required configuration and secrets.

Provider credentials

For GitHub App and Premium BYOC installations, store provider credentials in the Previewops dashboard under Credentials. CLI and self-hosted deployments may instead supply the corresponding environment variables at runtime. Never commit credentials to .previewops.yaml, workflow files, Dockerfiles, or repository history.

See Credentials for the exact keys and Supported providers for provider availability.