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.

Secrets & Environment Variables

You can store arbitrary app secrets (for example STRIPE_SECRET_KEY or a third-party API token) in the Previewops dashboard. They are encrypted at rest and injected as container environment variables into every preview deploy — no changes to .previewops.yaml required.

This is the recommended way to supply runtime secrets to preview environments. Values stored here are never committed to git.

How to add a secret

Log in to the Previewops dashboard.
Navigate to Installations → select your organisation.
Click Credentials.
Scroll to the Secrets & Environment Variables section.
Enter the Name (e.g. STRIPE_SECRET_KEY) and Value.
Click Save secret.

The secret is available immediately on the next deploy — there is no need to redeploy Previewops.

How to delete a secret

In the Secrets & Environment Variables section, find the row you want to remove.
Click Delete.

The secret is removed from all subsequent deploys. Running previews are not affected until they are redeployed.

Priority rules

When the same key appears in multiple places, the last write wins:

.previewops.yaml env: block — lowest priority
Secrets stored in the dashboard — override env: values
Preview DB add-on DATABASE_URL — always wins (injected last)

Security note

Secrets are encrypted at rest in Previewops storage. At deploy time they are injected as plain container environment variables, so they are visible to anyone with cloud admin console access to the account that hosts your preview environment.

💡 Storing DATABASE_URL? Consider the Preview DB add-on instead — it gives each PR its own isolated database branch automatically, and DATABASE_URL is injected with no dashboard configuration needed.

Available on all plans

Secrets & Environment Variables are available on all plans (Free, Pro, Enterprise, Custom, and Premium BYOC).

Which plans require BYOC cloud 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

Cloud provider credentials are added through a 4-step wizard in the dashboard:

Log in to the Previewops dashboard.
Click Credentials in the left sidebar.
Click Add cloud provider.
Step 1 — Select provider: Choose your cloud platform from the card grid.
Step 2 — Configure credentials: Enter the required fields for the selected provider (e.g. API key, project ID, service account key).
Step 3 — Advanced configuration (optional): Fine-grained settings such as region overrides. Click Skip if you're unsure — these can be added or changed later via the update flow.
Step 4 — Review: Click Test connection.
If validation passes, click Save credentials.
If validation fails, you can either fix the values and test again or choose Override and save anyway.

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

Validation status in the table

Each stored cloud credential row now includes:

Last Tested — when stored credentials were last validated.
Status — Active, Inactive, or Pending.

Use the row-level Test action to validate already-saved credentials at any time (for example, after a key rotation or expected expiry window).

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	Required	Description
`GCP_PROJECT_ID`	✅	Your GCP project ID
`GCP_SA_KEY`	✅	Service account JSON key — use the file upload in the wizard to encode automatically, or paste the raw JSON
`GCP_REGION`	☐	Region override (default: `us-central1`). Set in Advanced configuration.
`GCP_ARTIFACT_REGISTRY_REPO`	☐	Full registry path, e.g. `us-central1-docker.pkg.dev/my-project/previewops`. Set in Advanced configuration.
`GCP_LABELS`	☐	Comma-separated GCP resource labels applied to Cloud Run services, e.g. `env=preview,team=eng`. Set in Advanced configuration.

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

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	Required	Description
`SSH_PRIVATE_KEY`	✅	Private SSH key (PEM format) for connecting to your server
`DOCKER_SSH_HOST`	✅	SSH hostname or IP address of the server
`DOCKER_SSH_PORT`	—	SSH port (default: `22`)
`DOCKER_SSH_USER`	—	SSH username (default: `ubuntu`)
`DOCKER_SSH_HOST_KEY_FINGERPRINT`	—	SHA256 fingerprint of the server's ED25519 host key (recommended — prevents MITM). Obtain with `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub` on the server.
`DOCKER_SSH_BASE_URL`	—	Base URL of the server (e.g. `http://1.2.3.4`) — used to build the preview URL
`DOCKER_SSH_BASE_DIR`	—	Remote working directory for deploy files (default: `/srv/previews`). The SSH user must have write access — run `sudo mkdir -p /srv/previews && sudo chown $USER:$USER /srv/previews` on the server if using the default.
any other key	—	Injected as an environment variable into your containers at deploy time (e.g. `DATABASE_URL`, `REDIS_URL`). Values from `.previewops.yaml` `env:` take precedence when the same key appears in both.

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

Render (`render`)

Key	Required	Description
`RENDER_API_KEY`	✅	API key from the Render dashboard
`RENDER_OWNER_ID`	✅*	Your Render owner or team ID (`usr_…` or `tea_…`). *Optional if `providerConfig.ownerId` is set in `.previewops.yaml`.

When both RENDER_API_KEY and RENDER_OWNER_ID are stored as credentials, no .previewops.yaml configuration is required to deploy with the render provider.

See providers/render.md for full setup instructions.

Railway (`railway`)

Key	Required	Description
`RAILWAY_API_TOKEN`	✅	API token from Railway Account Settings → Tokens
`RAILWAY_PROJECT_ID`	✅*	Railway project UUID. *Optional if `providerConfig.projectId` is set in `.previewops.yaml`.
`RAILWAY_ENVIRONMENT_ID`	✅*	Railway environment UUID (e.g. the `production` environment). *Optional if `providerConfig.environmentId` is set in `.previewops.yaml`.

Both IDs are visible in the Railway dashboard URL when you have the environment open: https://railway.com/project/{projectId}?environmentId={environmentId}

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

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	Required	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
`AZURE_RESOURCE_GROUP`	✅	Azure resource group name
`AZURE_MANAGED_ENV`	✅	Container Apps managed environment name
`AZURE_ACR_SERVER`	✅	ACR login server (e.g. `myregistry.azurecr.io`)
`AZURE_REGISTRY_NAME`	✅	ACR name without the `.azurecr.io` suffix
`AZURE_LOCATION`	☐	Azure region (default: `eastus`)

The bottom 5 fields (AZURE_RESOURCE_GROUP through AZURE_LOCATION) can alternatively be set via providerConfig: in your .previewops.yaml. If already configured there, you can skip them here.

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

Custom LLM (`custom-llm`)

Required when the Custom LLM add-on is active. Allows Previewops to use your own OpenAI or Anthropic API key for AI-powered QA analysis and performance insights instead of the operator's key.

Prerequisite: activate the Custom LLM add-on from the Add-ons page first (free on all plans). See add-ons.md.

Key	Required	Description
`LLM_API_KEY`	✅	Your API key — `sk-…` for OpenAI or `sk-ant-…` for Anthropic
`LLM_PROVIDER`	✅	Select openai or anthropic from the dropdown in the credentials form
`LLM_MODEL`	☐	(Advanced Options) Choose the model for your selected provider. The dropdown updates automatically when you change the provider (see supported models below). Defaults to `gpt-4o` (OpenAI) or `claude-sonnet-4-5` (Anthropic) when omitted.
`LLM_MAX_TOTAL_PATCH_CHARS`	☐	(Advanced Options) Total character budget for all file diffs in a single QA analysis request. Increase if analysis is consistently truncated on large PRs; decrease to reduce token usage. Default: `20000`.
`LLM_QA_MAX_FILES_FOR_PROMPT`	☐	(Advanced Options) Maximum number of changed files included in the analysis prompt. Increase for very large PRs; decrease to reduce token usage. Default: `40`.
`LLM_QA_FALLBACK_TOTAL_PATCH_CHARS`	☐	(Advanced Options) Reduced diff budget used automatically when the initial analysis request is rejected by the model due to size. Default: `8000`.
`LLM_QA_MAX_OUTPUT_TOKENS`	☐	(Advanced Options) Maximum tokens requested for the analysis response. Increase if reports are being cut off. Default: `1200`.

Note: Both LLM_PROVIDER and LLM_MODEL are dropdowns — free-text entry is not accepted. LLM_MODEL is under Advanced options and is optional.

Supported models per provider:

Provider	Models
openai	`gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`, `o1`, `o3-mini`
anthropic	`claude-opus-4-5`, `claude-sonnet-4-5`, `claude-3-5-haiku-20241022`

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:

Log in to the Previewops dashboard.
Click Credentials in the left sidebar.
Set Provider key to preview-db.
Add the key PREVIEW_DB_STAGING_URL with your staging database connection string.
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.

Named Credential Profiles

Available on: Premium BYOC and Custom plans.

Named credential profiles let you store multiple sets of credentials for the same provider under distinct names and reference them explicitly when deploying. This is useful when a team has more than one cloud account, region, or project for the same provider.

Examples:

gcp-eu and gcp-us — two Google Cloud projects in different regions
fly-staging and fly-prod — different Fly.io organisations
team-a and team-b — credentials scoped to different sub-teams

How it works

Every credential stored in Previewops has a Credential Name — a short identifier you choose (lowercase letters, digits, and hyphens; max 30 characters). When you have multiple credentials for the same provider, you reference them at deploy time using the --name flag:

/deploy-previewops --name=gcp-eu
/deploy-previewops --name=fly-staging

Previewops looks up the named credential, infers the provider automatically, and uses those credentials for the build and deploy. The provider does not need to be specified separately when --name is used.

You can still combine --name with --provider if you want to be explicit:

/deploy-previewops --provider=fly --name=fly-staging

If --provider and --name are both given but refer to different providers, Previewops posts a conflict error and does not deploy.

How to add a named credential profile

Log in to the Previewops dashboard.
Click Credentials in the left sidebar.
Click Add cloud provider.
Fill in the credentials for your provider as usual.
In the Credential name field, enter a unique identifier for this profile (e.g. gcp-eu, fly-staging).
Click Save credentials.

You can add as many named profiles as you need — one per cloud account, region, or team.

Credential names are permanent. Once a profile is saved, its name cannot be changed. The name is how Previewops resolves --name=<profile> in deploy commands — changing it after creation would break any existing PR comments or .previewops.yaml configs that reference it. If you need a different name, delete the profile and create a new one.

How to deploy using a named credential

In a PR comment, use the --name flag:

/deploy-previewops --name=gcp-eu

Or trigger from the Deploy new preview modal in the dashboard — after selecting a provider, a Credential Profile dropdown appears listing all profiles saved for that provider.

How to delete a named credential

In the Credentials page, find the row for the profile you want to remove.
Click Delete on that row.

The profile is removed immediately. Any previews already deployed with that credential continue to run until they expire or are deleted. Re-deploying after deletion will require specifying a different credential name.

Validation

Each named profile can be validated independently. Click Test on a credential row in the dashboard to run a live API check against your cloud provider. The validation status (Active, Inactive, or Pending) is shown per profile.

Default credentials

If your plan supports named credentials but you deploy without --name, Previewops looks for a default credential for the provider specified in .previewops.yaml (or --provider). If exactly one profile is stored for that provider, it is used automatically. If multiple profiles exist and none is marked as default, Previewops posts a comment listing the available names and asks you to re-run with --name=<profile>.