Create an Environment using Platform as Code

Define an Environment in a YAML or JSON file and synchronize it from your Git repository.

Important

Platform as Code is not Infrastructure as Code. PaC manages the Axio platform itself (projects, workspaces, environments, policies, runners, and more). It is not the same as axio.yaml stack blueprint files in IaC repositories, which describe stack provisioning.

An Environment manifest requires a parent Workspace (and typically a Project). Define and synchronize Project and Workspace manifests first, then add the Environment referencing spec.workspace and spec.project.

Connect repositories under Administration → Integrations → Source Control, then synchronize from Platform as Code → Synchronizations.

Prerequisites

A Git provider connection configured in Administration → Integrations → Source Control.
A repository registered for Platform as Code synchronization (created automatically on first Sync now, or configured explicitly).
The target Project and Workspace already defined in Git and synchronized into Axio.
Permission to synchronize:
- Administrators — full PaC management (pac:manage): connect repos, configure schedules, sync, and approve plans.
- Members (scoped) — can run Sync now on Admin-configured repositories for in-scope product resources.
- Viewers — read-only access to catalog, resources, and sync history.

Step-by-Step Guide

Ensure parent Project and Workspace exist

Confirm the Project and Workspace manifests are in Git and synchronized. Use workspace and project slugs from their metadata.name values (e.g. ecommerce, development) in the Environment spec.

Define the Environment

Create a YAML or JSON file containing the Environment definition.

metadata.name — Stable identifier; becomes the environment slug (unique within the workspace).
spec.displayName — Human-readable name shown in the UI (falls back to metadata.name if omitted).
spec.workspace — Required. References the parent Workspace by slug or ID.
spec.project — Recommended. References the parent Project by slug or ID. Helps resolve the workspace unambiguously.
spec.description — Optional summary.
spec.type — Optional: DEVELOPMENT, STAGING, PRODUCTION, or CUSTOM (defaults to DEVELOPMENT on create).
spec.deploymentGovernance — Optional. Configure deployment operators, approvers, and self-approval in Git (alternative to UI Assign owner).

Do not author a status block — Axio generates and manages status automatically.

Commit and push

Commit the Environment definition and push it to the branch configured for synchronization (typically main).

Synchronize with Axio

Go to Platform as Code → Synchronizations and synchronize the connected repository.

Manual synchronization

Click Sync now to fetch Git changes, validate manifests, resolve dependencies, build a sync plan, and apply the Environment.

Scheduled synchronization

Enable the Auto switch and choose an interval (or daily schedule) to periodically reconcile the repository.

Review the sync run

Check Recent runs for validation results, resources created/updated, and any approval required.

Environment created

After a successful synchronization, the Environment appears under the referenced Workspace on Organization → Environments with a Git-managed badge. Git-managed environments must be updated through Git synchronization — manual edits in the UI are restricted.

YAML JSON

apiVersion: platform.axio.io/v1
kind: Environment

metadata:
  name: production

spec:
  displayName: Production Environment
  project: ecommerce
  workspace: development
  description: Production deployment target
  type: PRODUCTION

{
  "apiVersion": "platform.axio.io/v1",
  "kind": "Environment",
  "metadata": {
    "name": "production"
  },
  "spec": {
    "displayName": "Production Environment",
    "project": "ecommerce",
    "workspace": "development",
    "description": "Production deployment target",
    "type": "PRODUCTION"
  }
}

Repository structure

Nested directories are supported. Axio recursively discovers YAML/JSON manifest files under the repository working directory.

platform-config/
├── projects/
│   └── ecommerce.yaml
├── workspaces/
│   └── development.yaml
└── environments/
    ├── staging.yaml
    └── production.yaml

spec.workspace must match the Workspace manifest's metadata.name. When both are new, synchronize Project → Workspace → Environment in dependency order (a single sync run handles this if all files are present).

Field reference

Field	Required	Description
`apiVersion`	Yes	Must be `platform.axio.io/v1`
`kind`	Yes	Must be `Environment`
`metadata.name`	Yes	Unique environment slug within the workspace
`spec.displayName`	No	Display name in the Axio UI
`spec.workspace`	Yes	Parent Workspace slug or ID
`spec.project`	Recommended	Parent Project slug or ID; required when the workspace slug is ambiguous across projects
`spec.description`	No	Optional description
`spec.type`	No	`DEVELOPMENT`, `STAGING`, `PRODUCTION`, or `CUSTOM` (default `DEVELOPMENT`)
`spec.deploymentGovernance`	No	Owners, approvers, and self-approval policy (see below)
`status`	No	Do not author — system-managed

Naming rules: Environment slugs must be unique within the parent workspace. Conflicting slugs fail validation during synchronization.

System environments: The auto-provisioned Default Environment is a protected system resource and cannot be modified or deleted through Platform as Code.

Workspace assignment: PaC update changes name, description, type, and governance — not workspace reassignment. Move environments between workspaces using the UI edit flow for non-Git-managed resources.

What happens next?

The Environment is created or updated in Axio after a successful synchronization.
The Environment appears under the referenced Project and Workspace on Organization → Environments with a Git-managed badge.
Future changes flow through Git — edit the manifest, commit, push, and synchronize again.
You can run Sync now at any time or enable Auto scheduled synchronization.
Review sync results under Recent runs and Platform as Code → History.
Deploy Stacks into the environment, or define stack manifests and synchronize them next.

Git-managed environments

Environments created through Platform as Code are managed from Git. The UI shows a Git-managed badge.

Update the environment by editing the manifest in Git and synchronizing
Manual rename/delete in the UI is blocked for Git-managed environments
Git-managed environments cannot be unassigned from their workspace via the UI
Removing an environment from Git may stage a pending removal — review under Synchronizations

Sensitive manifests and approval

Optional metadata.sensitive: true marks a manifest so Git-driven updates or removals require sync plan approval before apply.

This is separate from the UI Sensitive checkbox (delete/archive/destroy protection), configured when editing an environment in the UI.

Tip

Keep Environment definitions in Git alongside Projects and Workspaces in the same repository. Use type: PRODUCTION for production targets and set allowSelfApproval: false in governance for separation of duties. Browse templates under Platform as Code → Catalog.