Platform as Code Create a Project using Platform as Code

Define a Project in a YAML or JSON file and synchronize it with Axio from your Git repository.

Warning

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.

Ensure that your Git repository is connected to Axio before proceeding. Connect repositories under Administration → Integrations → Source Control, then synchronize from Platform as Code → Synchronizations.

Info

Prerequisites

  • A Git provider connection (GitHub, GitLab, Bitbucket, or Azure DevOps) configured in Administration → Integrations → Source Control.
  • A repository registered for Platform as Code synchronization (created automatically on first Sync now, or configured explicitly).
  • 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

1

Connect your Git repository

If not already connected, go to Administration → Integrations → Source Control, connect your provider, and register the repository. Set the working directory to the folder that contains your platform manifests (default: platform-config).

2

Define the Project

Create a YAML or JSON file containing the Project definition.

  • metadata.name — Stable identifier; becomes the project slug (URL-safe).
  • spec.displayName — Human-readable name shown in the UI (falls back to metadata.name if omitted).
  • spec.description — Optional summary.

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

3

Commit and push

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

4

Synchronize with Axio

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

Manual synchronization

Click Sync now to immediately fetch Git changes, validate manifests, build a sync plan, and apply the Project definition.

Scheduled synchronization

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

Review the sync run

Check Recent runs on the same page for validation results, resources created/updated, and any approval required. Some changes to sensitive manifests require approval before apply.

5

Project created

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

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

metadata:
  name: ecommerce

spec:
  displayName: Ecommerce Project
  description: Project for ecommerce services

{
  "apiVersion": "platform.axio.io/v1",
  "kind": "Project",
  "metadata": {
    "name": "ecommerce"
  },
  "spec": {
    "displayName": "Ecommerce Project",
    "description": "Project for ecommerce services"
  }
}

Repository structure

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

platform-config/
└── projects/
    ├── ecommerce.yaml
    └── payments.yaml

Alternative layouts (e.g. platform/projects/) work as long as the repository working directory is configured correctly in Source Control.

Field reference

Field Required Description
apiVersion Yes Must be platform.axio.io/v1
kind Yes Must be Project
metadata.name Yes Unique slug within the organization. Used to match the project on updates. Names are slugified (e.g. Ecommerce Project → ecommerce-project).
spec.displayName No Display name in the Axio UI
spec.description No Optional description
status No Do not author — system-managed

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

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

What happens next?

  • The Project is created or updated in Axio after a successful synchronization.
  • The Project appears under Organization → Projects with a Git-managed badge.
  • Future changes to the Project 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 a Workspace manifest that references this project (spec.project: ecommerce) and synchronize it next.
Git-managed

Git-managed projects

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

  • Update the project by editing the manifest in Git and synchronizing
  • Manual rename/delete in the UI is blocked for Git-managed projects
  • Removing a project from Git may stage a pending removal — review and confirm under Synchronizations
Sensitive

Sensitive manifests and approval

Optional metadata.sensitive: true (or label platform.axio.io/sensitive: "true") marks a manifest so that Git-driven updates or removals require sync plan approval before apply.

This is separate from the UI Sensitive checkbox on projects (delete/archive/destroy protection), which is configured when editing a project in the UI.

Tip

Tip

Store Project definitions in Git to maintain version history, review changes through pull requests, and manage configuration consistently across environments. Browse available resource kinds and generated templates under Platform as Code → Catalog.