Credentials Guide

Previewops deploys previews to your cloud account. This is what BYOC (Bring Your Own Cloud) means — your credentials, your infrastructure, your bill. Previewops orchestrates the deployments on your behalf.

Which plans require credentials

Plan Credentials required
Free Yes — you provide credentials for your chosen provider
Premium BYOC Yes — you provide credentials for your chosen provider
Pro Optional — Previewops can use its own infrastructure, or you can BYOC
Enterprise Optional
Custom Optional

If you are on the Free or Premium BYOC plan and have not yet added credentials, your first deploy attempt will result in a bot comment prompting you to add them before proceeding.

How to add credentials

  1. Log in to the Previewops dashboard.
  2. Navigate to Installations → select your organisation.
  3. Click Credentials.
  4. Select your provider from the dropdown.
  5. Enter the credential key-value pairs for that provider (see the provider-specific sections below).
  6. Click Save.

Credentials take effect immediately — no redeploy of Previewops is required.

Credentials per provider

Cloud Run (cloud-run)

Plan Credentials required
Pro, Enterprise, Custom None — Previewops manages GCP on your behalf
Free, Premium BYOC Yes — you provide your own GCP project credentials

For Free and Premium BYOC plans, add the following keys in the dashboard:

Key Description
GCP_PROJECT_ID Your GCP project ID
GCP_SA_KEY Base64-encoded service account JSON key
GCP_ARTIFACT_REGISTRY_REPO Full registry path, e.g. us-central1-docker.pkg.dev/my-project/previewops
GCP_REGION Optional region override (default: us-central1)

See providers/cloud-run.md for step-by-step setup instructions.

For other providers, add the following keys in the dashboard:

Fly.io (fly)

Key Required Description
FLY_API_TOKEN ✅ Personal access token from fly.io/user/personal_access_tokens
FLY_ORG_SLUG ✅* Your Fly.io organisation slug (e.g. my-fly-org). *Can be omitted if providerConfig.orgSlug is set in .previewops.yaml.
FLY_REGION Fly.io region code (e.g. lhr, ams). Defaults to iad. Can be overridden per-repo via providerConfig.region in .previewops.yaml.

When all three keys are stored as credentials, no .previewops.yaml is required to deploy with the fly provider.

See providers/fly.md for full setup instructions.

Hetzner (hetzner)

Key Description
HETZNER_API_TOKEN API token from the Hetzner Cloud Console
HETZNER_SSH_KEY Private SSH key (PEM format) matching a key registered in your Hetzner account

See providers/hetzner.md for full setup instructions.

Docker over SSH (docker-ssh)

Key Description
SSH_PRIVATE_KEY Private SSH key (PEM format) for connecting to your server

See providers/docker-ssh.md for full setup instructions.

Render (render)

Key Description
RENDER_API_KEY API key from the Render dashboard

See providers/render.md for full setup instructions.

Railway (railway)

Key Description
RAILWAY_API_TOKEN API token from the Railway dashboard

See providers/railway.md for full setup instructions.

DigitalOcean (digitalocean)

Key Description
DIGITALOCEAN_TOKEN Personal access token from the DigitalOcean control panel
DO_SSH_PRIVATE_KEY Private SSH key (PEM format) matching a key registered in your DO account

See providers/digitalocean.md for full setup instructions.

AWS Lightsail (aws-lightsail)

Key Description
AWS_ACCESS_KEY_ID AWS access key ID
AWS_SECRET_ACCESS_KEY AWS secret access key
AWS_SSH_PRIVATE_KEY Private SSH key (PEM format) for Lightsail instance access

See providers/aws-lightsail.md for full setup instructions.

AWS ECS (aws-ecs)

Key Description
AWS_ACCESS_KEY_ID AWS access key ID
AWS_SECRET_ACCESS_KEY AWS secret access key

See providers/aws-ecs.md for full setup instructions.

Azure Container Apps (azure-container-apps)

Key Description
AZURE_CLIENT_ID Azure service principal client ID
AZURE_CLIENT_SECRET Azure service principal client secret
AZURE_TENANT_ID Azure Active Directory tenant ID
AZURE_SUBSCRIPTION_ID Azure subscription ID

See providers/azure-container-apps.md for full setup instructions.

Preview DB add-on (preview-db)

The Preview DB add-on requires one credential: your staging database URL. Previewops syncs this into a preview parent branch nightly so every PR preview gets a fresh, isolated fork.

Prerequisite: the Preview DB add-on must be active on your subscription. See add-ons.md.

Key Description
PREVIEW_DB_STAGING_URL Postgres connection string for your staging database. Must be publicly reachable. Example: postgresql://user:pass@db.staging.example.com:5432/myapp

To add this credential:

  1. Log in to the Previewops dashboard.
  2. Navigate to Installations → select your organisation → Credentials.
  3. Set Provider key to preview-db.
  4. Add the key PREVIEW_DB_STAGING_URL with your staging database connection string.
  5. Click Save.

Previewops will pick up the URL on the next nightly resync (or you can trigger an on-demand resync from the dashboard under Preview DB → Resync now). The staging URL is encrypted with Cloud KMS at rest — it is never stored in plaintext.

Security

Credentials are encrypted with Cloud KMS before being stored in the database. The plaintext values are never written to disk or included in logs. Only the Previewops process running in your organisation's deployment context can decrypt them.

If you need to rotate a credential, simply save new values in the dashboard — the old encrypted values are replaced immediately.