Work with file-based IOModel projects stored in a Git repository and edited through the IDE extension.
A Git-project is a file-based IOModel project that lives in a Git repository. Instead of being stored and versioned in the platform, its models and specifications are plain files you edit through the IDE extension (or directly), and version with Git.
Cloud project vs Git-project
Cloud projects are stored and versioned inside IOModel (with in-platform branches). A Git-project keeps content as files in your repository and uses Git for versioning. This page covers the Git-project workflow.
Expected directory layout
A Git-project is the same tree Studio uses. Full rules: File & Folder Structure.
my-project/
project.yaml
models.yaml
models/
...
specs/
meta.yaml
<group>/
meta.yaml
overview.mdx # leaf: no children, no attachments
topic/
index.mdx # folder: children or attachments
_attachments/Form follows content
Do not create a directory for every page. A leaf with no attachments stays
<page>.mdx. pages: entries are one URL segment; nested folders hold their
own meta.yaml. The directory is _attachments, not _assets.
project.yaml
project:
title: My Project
description: Architecture and specs versioned in Git
icon: Folder
features:
- specs
- modelBring existing files into a Git-project
Arrange your files
Place existing model YAML and spec MDX into the expected layout in your repository.
Add project.yaml
Declare the title, description, icon, and enabled features.
Add navigation meta
Provide meta.yaml files so groups and pages appear in the sidebar in the intended order.
Open in the IDE extension
Mapping existing content
| You have | Put it in | Result |
|---|---|---|
| Architecture YAML | models/ + models.yaml | Browsable model tree |
| Markdown/MDX docs | specs/<group>/ | Specification pages |
| Object/workflow files | attachments: on the owner | Tabs and handbook |
Versioning
A Git-project uses Git itself for history and collaboration:
- Commit and branch with your normal Git workflow.
- Review changes in pull requests alongside code.
- In-platform branches do not apply — Git is the source of versioning.
In-platform branches
Git-projects do not use IOModel’s in-platform branches. Use Git branches and pull requests for isolation and review.
Keep navigation meta.yaml files accurate. They control sidebar order and
which pages are visible.
Last updated on