# Versions and the built-in git

> An application is a git repository of typed artifacts with a reconciler that materialises them, and the git is real: a clone and push transport, per-repo authorisation and no existence oracle

Source: https://aipril.dev/docs/platform/versions

## An application is a repository

An [application](https://aipril.dev/docs/apps/under-the-hood.md) is a **git repository of typed artifacts** describing
desired state - the data model, processes, pages,
automations, connector configuration, roles, declared staff - plus a **reconciler** that materialises
them into live platform entities.

The model is catalogue → installation: a versioned package, installed into an organisation, with the
installation tracked separately from the package.

That gives the properties a database row cannot:

- **A diff between two versions**, in the ordinary sense of the word
- **A history with authorship**, per artifact
- **Rollback** as a checkout rather than as a compensating script
- **Branching and change requests** before anything reaches the live system
- **A fork per organisation**, so a customer's changes to an installed application are their own
  commits rather than a merge conflict with the vendor

## The git is real

There is a git transport mounted outside the API surface, with its own token authentication. It
spawns the actual git binary against the same repositories the platform maintains - not a second
storage layer with a git-shaped API.

So an engineer can `git clone` an application, edit it in their own editor, and `git push`. Useful
for bulk edits, refactors, and running CI against an application before it goes anywhere near
production.

Authorisation is per repository and mirrors the product's own rules: **clone authorises like reading
the app, push like authoring it.** A repository the caller may not act on returns *not found* rather
than *forbidden* - the same no-existence-oracle rule the rest of the platform's shared links follow.

Every repository access carries a real actor. There is no system identity that can act on a
repository without one, and a test asserts that instead of leaving it to convention.

## Three ways to author, one format

| Path | Who |
|---|---|
| The in-product agent | Describe what you want; it writes artifacts through the ops layer |
| MCP authoring tools | An external AI client - Claude Code, Cursor - writing the same artifacts |
| Clone and push | Your own engineers, in their own tooling |

All three produce the same artifacts in the same repository, so nothing about an application records
which path made it. Activation stays with an administrator in the product in every case.

## Versions and immutability

A published version is immutable: what was published is what installs, and it cannot be edited under
an installed base. The working draft persists after publishing, so the next iteration starts from
where you were, not from the published copy.

## Related

- [Applications under the hood](https://aipril.dev/docs/apps/under-the-hood.md) - artifact kinds, the reconciler, change
  requests.
- [Deployment](https://aipril.dev/docs/platform/environments/deployment.md) - the platform's own release path, which
  follows the same rule at a different level: a release is a commit.
- [Audit](https://aipril.dev/docs/platform/audit.md) - what is recorded when a version is installed.