Two version-control systems

When you build with Culvii, you're operating with two version-control systems at once:

Git	Culvii
Source of truth for code	Source of truth for deployed snapshots
Commit history	Version history (v1, v2, v3…)
Branches	Environments (dev, sandbox, prod)
git push	culvii deploy --env <env>
Tracks every change to every file	Tracks each deliberate promotion
No awareness of Culvii environments	No awareness of git commits

These two systems do not mirror each other, and you should not try to make them.

What this means in practice

A developer can commit to git fifty times while iterating on a workflow and run culvii deploy exactly once — when the workflow is ready. The fifty commits all live in git history. The single deploy creates one Culvii version.

The other direction works too: you can culvii deploy the same code from two different commits to two different environments. Maybe sandbox is on main, but prod is still on release/2025-04. Each environment has its own version history.

The CI/CD pattern

Most teams wire the two systems together via CI/CD. The most common shape:

Git event	What CI does
Merge to main	culvii deploy --env sandbox
Manual workflow dispatch	culvii deploy --env prod

This connects the two systems but doesn't conflate them. Git remains the source of truth for code. Culvii remains the source of truth for what's deployed where. CI is the bridge.

See How-to → Set up CI/CD for culvii deploy for a worked example.

What we don't do

We don't:

• Tag git commits when you deploy.
• Read git commit hashes into Culvii version metadata.
• Read git branches as environment markers.

You can do any of these in your CI script if your team wants. The platform doesn't insist.

Where this gets confusing

Two failure modes we've seen:

• Mistaking culvii deploy for git push. A git push doesn't deploy. You can push to a branch all day; nothing changes in any Culvii environment until you run culvii deploy.
• Mistaking environments for branches. If you have main → sandbox and release/* → prod, that's a CI convention. The environment isn't defined by the branch. You can manually deploy any code to any environment from the CLI; the environment is a Culvii concept, the branch is a git concept.

Treat them as two separate systems with a deliberate connection in CI, and the model stays clear.