Create a Workspace using Platform as Code

Define a Workspace in a YAML or JSON file and synchronize it with Axio 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.

A Workspace manifest requires a parent Project. Define and synchronize the Project first, then add the Workspace manifest referencing 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 already defined in Git and synchronized into Axio (or present from a prior sync in the same repository).
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 the parent Project exists

The Workspace depends on a Project. Confirm the Project manifest (for example projects/ecommerce.yaml) is in Git and has been synchronized successfully. Use the project slug from metadata.name (e.g. ecommerce) in spec.project.

Define the Workspace

Create a YAML or JSON file containing the Workspace definition.

metadata.name — Stable identifier; becomes the workspace slug (unique within the project).
spec.displayName — Human-readable name shown in the UI (falls back to metadata.name if omitted).
spec.project — Required. References the parent Project by slug or ID.
spec.description — Optional summary.

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

Commit and push

Commit the Workspace 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 the Project dependency, build a sync plan, and apply the Workspace.

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. Changes to sensitive manifests may require approval before apply.

Workspace created

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

YAML JSON

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

metadata:
  name: development

spec:
  displayName: Development Workspace
  project: ecommerce
  description: Development workspace

{
  "apiVersion": "platform.axio.io/v1",
  "kind": "Workspace",
  "metadata": {
    "name": "development"
  },
  "spec": {
    "displayName": "Development Workspace",
    "project": "ecommerce",
    "description": "Development workspace"
  }
}

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
    └── staging.yaml

spec.project: ecommerce must match the Project manifest's metadata.name (slug). Apply Project manifests before Workspace manifests in the same sync when both are new.

Field reference

Field	Required	Description
`apiVersion`	Yes	Must be `platform.axio.io/v1`
`kind`	Yes	Must be `Workspace`
`metadata.name`	Yes	Unique workspace slug within the parent project. Used to match the workspace on updates.
`spec.displayName`	No	Display name in the Axio UI
`spec.project`	Yes	Parent Project slug or ID. Validation fails if the project cannot be resolved.
`spec.description`	No	Optional description
`status`	No	Do not author — system-managed

Naming rules: Workspace slugs must be unique within the parent project. Renaming metadata.name changes the slug; conflicting slugs fail validation during synchronization.

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

Project assignment: New workspaces are created under the project referenced in spec.project. Moving a workspace to another project is handled through the UI edit flow, not by changing spec.project on an existing Git-managed workspace.

What happens next?

The Workspace is created or updated in Axio after a successful synchronization.
The Workspace appears under the referenced Project on Organization → Workspaces 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 for immediate reconciliation.
You can enable Auto scheduled synchronization to apply Git changes on a recurring interval.
Push webhooks (when configured) can trigger synchronization without manual Sync now.
Review sync results under Recent runs and Platform as Code → History.
Define an Environment manifest referencing this workspace and project, then synchronize it next.

Git-managed workspaces

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

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

Sensitive manifests and approval

Optional metadata.sensitive: true (or label platform.axio.io/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), which is configured when editing a workspace in the UI.

Tip

Keep Workspace definitions in Git to maintain version history and manage changes through pull requests. Browse resource kinds and templates under Platform as Code → Catalog. Define Projects and Workspaces in the same repository so dependency order is satisfied on each sync.