Environments — proxifai Docs

An environment is a named deployment target for a service. Each environment renders and applies that service’s manifests into its own Kubernetes namespace, driven by a GitOps repository. Manage them under Deploy → Environments (scoped to the picked service) or via /api/v1/projects/{projectId}/environments.

Tiers

Every environment has a tier, which the platform uses for ordering, promotion, and defaults:

Tier	Typical use
`dev`	Day-to-day development target
`qa`	Integration / QA testing
`preprod`	Staging that mirrors production
`prod`	Production
`preview`	Auto-created, auto-expiring per-PR environments — see Previews

GitOps source

Each environment points at a deployments repository and is reconciled from it:

Field	Meaning
`deploymentsBranch`	Branch the reconciler tracks
`deploymentsPath`	Path within the repo to render (`kustomize build <path>`)
`autoSync`	Reconcile automatically on new commits
`syncIntervalSeconds`	Poll interval when auto-sync is on
`lastAppliedSha` / `lastSyncAt` / `lastSyncError`	Last successful apply and any failure surfaced back to the UI

Set the source with PUT /api/v1/projects/{projectId}/environments/{envId}/source, trigger an on-demand reconcile with POST .../sync, and watch live progress over SSE at GET .../events.

Git is the single source of truth. A UI edit, a CLI command, or a raw git push to the deployments repo all converge on the same reconciler — a push typically applies in under two seconds.

Approval gates

An environment can require human approval before changes apply. The approval rule (PUT .../approval-rule) supports:

requiredApprovals — how many approvals are needed
approverUserIds / approverRoleNames — who may approve
preventSelfApproval — the PR author can’t approve their own change
dismissStaleApprovalsOnPush — new commits invalidate prior approvals

Approvals show up in the Inbox with inline approve/reject actions and in the service’s approvals list (GET /api/v1/projects/{id}/approvals).

Promotion

Promote a known-good build from one environment to the next instead of rebuilding:

promoteFromEnvironmentId — the parent environment this one promotes from (e.g. preprod → prod)
promoteRequireApproval — require approval on promote

Commit a promotion with POST /api/v1/projects/{projectId}/promotions/commit.

Managed vs GitOps-managed

The managed flag distinguishes environments proxifai manages directly (UI-driven) from those reconciled purely from a GitOps repo you own. Both apply through the same pipeline.

Namespaces & hostnames

Each environment binds to a Kubernetes namespace allocation; call POST .../ensure-namespace to allocate one. Manage allocations under /api/v1/projects/{projectId}/namespaces.
On Enterprise, attach a custom hostname (BYO domain via Cloudflare-for-SaaS) with POST .../hostnames; check status with .../hostnames/{id}/recheck.
Set the Insights log/metric retention tier per environment with PUT .../retention.

Deploying & rolling back

pfai deploy                 # open / update a deploy PR for the current repo
pfai deploy apply           # apply a planned deployment
pfai deploy observe         # follow a rollout in real time
pfai deploy rollback        # roll back to a previous revision

The corresponding API: POST /api/v1/projects/{projectId}/deployments/preview (dry-run plan), .../deployments/commit (apply), and .../deployments/override (force).