Git sync repository layout

From 6.0.0, a git-synced repository is organised by object type first — scripts under scripts/, flows under flows/, resources under resources/, and so on — rather than mirroring Orvanta’s internal folder paths the way earlier versions did. This page covers that layout, how to generate a ready-to-push repository from a workspace (“Initialise repository”), pushing it to GitHub, and what changes for the CLI.

For configuring which deploys a connected repository tracks, see Git sync. For the git_repository connection itself — personal access tokens vs. the GitHub App — see Git Integration.

Upgrading from before 6.0.0

An existing git-synced repository uses the old, pre-6.0.0 layout and must be re-initialised — see The CLI hard cut below. This is also covered in the 6.0.0 upgrade guide.

The repository layout

Every object type gets its own top-level directory. <folder> is the folder the object lives in inside Orvanta; a metadata sidecar is written alongside the object’s own content file wherever the object needs one that its native format can’t hold.

What	Repository path
CLI config (written once, at initialisation)	orvanta.yaml
Scripts	scripts/<folder>/<name>.<ext> + <name>.script.yaml
Flows (DAG)	flows/dag/<folder>/<name>/flow.yaml
BPMN flows	flows/bpmn/<folder>/<name>.bpmn + <name>.bpmn_flow.yaml
CMMN cases	flows/cmmn/<folder>/<name>.cmmn + <name>.cmmn_case.yaml
DMN decisions	decisions/dmn/<folder>/<name>.dmn + <name>.dmn_decision.yaml
Data migrations	data-migrations/<folder>/<name>.yaml
Resources	resources/<folder>/<name>.yaml
Variables	variables/<folder>/<name>.yaml
Schedules	schedules/<folder>/<name>.yaml
Triggers	triggers/<kind>/<folder>/<name>.yaml (<kind> is the trigger type — http, websocket, kafka, sqs, gcp, azure, nats, postgres, mqtt, or email)
Folders	folders/<name>.yaml
Resource types	resource-types/<name>.yaml
Groups	groups/<name>.yaml
Workspace members	users/<email>.yaml
Dependency manifests	dependencies/<manifest> — package.json, requirements.in, or composer.json, unchanged, since the manifest itself is the content
An object owned by a user rather than a folder	users/<user>/<type directory>/<name>… — for example users/alice/scripts/job.py
An object owned by a group	groups/<group>/<type directory>/<name>…

Metadata sidecars are YAML. A kind with only one file at a given name drops the kind suffix (resources/a/db.yaml, not resources/a/db.resource.yaml) because the directory already says what it is; a kind with two files sharing a stem — a script’s code and its sidecar, a BPMN flow’s .bpmn and its sidecar — keeps the suffix so the two halves are easy to tell apart at a glance.

This mapping is applied only when a repository is written or read — nothing about how paths are stored or how permissions are resolved inside Orvanta changed. The same mapping is used whichever writer produces the repository: a deploy-triggered commit, a workspace export, the “Initialise repository” ZIP, or a direct push into a newly connected repository, so a checkout looks the same regardless of which of those wrote it.

Flow inline scripts

A DAG flow’s steps do not carry their code inline inside flow.yaml; each step’s code (and lock file, when it has one) living in its own file next to flow.yaml, referenced from it as !inline <file>:

flows/dag/etl/daily/
  flow.yaml            # content: !inline fetch_data.py
  fetch_data.py
  fetch_data.lock

This keeps a flow’s diffs to the step that actually changed, instead of one flow.yaml with escaped code inside it. Step files are named after the step’s summary (or its id), lower-cased and Unicode-normalised, with whitespace turned into _ and path separators, Windows-forbidden and control characters removed. Names are unique within a flow, compared case-insensitively so a checkout works on macOS and Windows: a second step that cleans to fetch becomes fetch_1, the next fetch_2, from one counter per flow. A step with no usable name is called inline_script_0 (or the next counter), and a name too long for a filesystem is cut before it is compared. :::

Initialising a repository

Initialise repository generates a repository from a workspace’s current objects, laid out as above and ready to push to GitHub. It works from an empty workspace (nothing to export yet — you still get the scaffold below) and from a populated one. It’s a workspace-admin action, available from Git sync settings, both before any repository is connected (the onboarding case) and from an already-configured one.

What it includes is exactly what a deploy would sync: the target repository’s own git-sync filters if you’re initialising against an already-configured connection, or the workspace defaults (everything under f/**) if there’s none yet. An object whose name or path can’t be placed in the layout (for example, one saved before Orvanta enforced today’s naming rules) is skipped, and named in a warning rather than silently dropped.

Besides your objects, the generated repository includes:

• orvanta.yaml — the workspace binding and sync filters, in the CLI’s own config format.
• README.md — explains the layout and the push/connect steps below.
• .gitignore, and an optional .github/workflows/orvanta-sync.yml if you asked for a workflow that runs orvanta sync push for you.
• A .gitkeep placeholder in every included type directory that has no object yet, so the layout is visible even in a near-empty repository.

What’s deliberately left out: secret variable values (written as an empty string, never the ciphertext a normal sync would write), workspace settings, and the encryption key — none of these are ever exported this way, regardless of what you’ve configured to include.

What’s not left out, and worth checking before you push: a credential typed directly into a connection, a trigger, or a schedule’s arguments — rather than kept as a $var: reference — is exported in clear text, since it’s part of that object’s own definition. When your workspace has anything like this, the warnings name the affected fields, and the initialise flow tells you to keep the repository private.

Option A: download the ZIP and push it yourself

Choose a branch name, optionally include the GitHub Actions workflow, and optionally pick which configured repository’s filters to scope the export to. This downloads a ZIP you push with an ordinary local git workflow:

unzip orvanta-repo.zip -d my-workspace
cd my-workspace
git init
git add .
git commit -m "Initialise from Orvanta"
git branch -M main
git remote add origin https://github.com/<owner>/<repo>.git
git push -u origin main

Because this produces a single initial commit, push it to a new, empty repository on GitHub rather than one that already has history.

Option B: push straight into an already-connected repository

If a repository is already connected (see Connecting git sync below) and its configured branch doesn’t exist yet, the same action can push directly instead of downloading a ZIP — useful when you’d rather not round-trip through a local checkout for the very first commit. It checks the remote first and refuses if the branch already exists, whether that’s because it already holds an Orvanta-laid-out repository or unrelated content, and the push itself is never forced or rebased — if something else creates the branch in between, the push is rejected rather than overwriting it. If it’s refused, fall back to downloading the ZIP and pushing it yourself.

Pushing to GitHub

1. Create a new, empty repository on GitHub. Keep it private if the initialise warnings flagged any inline credentials.
2. If you’re using the GitHub App rather than a personal access token, install the Orvanta GitHub App on that repository (or the whole organisation) from Instance settings — see Git Integration for both authentication options.
3. Push using one of the two options above.

Connecting git sync

Once the repository exists with its initial commit, connect it the same way as any other git-sync repository, so future deploys keep committing to it:

1. If you haven’t already, install the Orvanta GitHub App on the repository (or the organisation) from Instance settings — or set up a git_repository connection with a personal access token instead.
2. In workspace settings, add the repository and configure which paths and types it should track — matching the filters you initialised with keeps the layout consistent going forward.

Full details — including what deploy-triggered git sync does and does not do today — are on the Git sync page.

A git_repository connection with the GitHub App enabled (is_github_app: true) only accepts a remote URL in one of these forms: https://github.com/<owner>/<repo>, ssh://git@github.com/<owner>/<repo>, or git@github.com:<owner>/<repo> (an optional .git suffix is fine). GitHub Enterprise Server is not supported for GitHub App sync — only github.com. A renamed repository’s redirect is no longer followed, so update the connection’s URL after a rename rather than relying on the old one still working. See the upgrade guide for the full detail on both of these.

Pinned deploy target

Each repository’s deploy destination (remote and branch) is pinned by a workspace admin. If the underlying resource or $var: later resolves to a different repository, deploys are refused rather than silently following the change; an admin must explicitly re-pin it from workspace settings after confirming the new target is intended. Existing entries are pinned automatically on upgrade, to whatever their resource resolves to at that moment. An entry added through the settings page is pinned immediately; an entry added through the CLI’s bulk sync push of settings.yaml starts unpinned and is pinned by a workspace admin’s first deploy through it or an explicit re-pin. Non-admin deploys through an unpinned entry are refused.

The CLI hard cut

The 6.0.0 CLI’s orvanta sync pull / orvanta sync push and orvanta init read and write only the layout on this page. This is a hard cut, not a compatibility mode:

• A checkout still in the pre-6.0.0 layout (an f/, u/, or g/ directory at its root) is refused outright, with an error pointing you at re-initialising the repository.
• A repository that has already moved to the new directory layout but still has old-style .json metadata sidecars (from before metadata moved to YAML) is also recognised as not-yet-6.0.0 and refused, rather than partially reparsed.
• Native git sync (the deploy-triggered path) doesn’t migrate an old-layout repository in place either — it logs a warning naming what needs fixing and leaves the old files alone.

Re-initialise, don’t hand-migrate. If you have an existing git-synced repository, generate a fresh repository with Initialise repository (either option above) and push it — rather than trying to reconcile the old layout by hand. Upgrade the CLI and the platform together: a pre-6.0.0 CLI can’t read a 6.0.0-synced repository, and a 6.0.0 CLI won’t read an old one.

Related

• Git sync: connecting a repository and configuring what it tracks.
• Git Integration: personal access tokens vs. the GitHub App.
• 6.0.0 upgrade guide: the full breaking-change list, including the pre-flight trigger-path check this layout change requires.
• Flows as artifacts: the artifacts a git-synced repository holds.