Skip to main content
Sync to Git connects your workspace to one GitHub repository and commits a new version of an item each time it changes. Use it to keep a reviewable history of your work, with who changed what and why.
  • Metrics, views, catalog metrics and Context pages are always committed.
  • Dashboards, MDX reports, slide decks and HTML dashboards are committed once they are published.
  • Notebooks and Workflows are committed when something they produce or feed is committed.
  • Anything you set to Tracked in GitHub or Controlled is committed too.
A project export or a scheduled snapshot is a copy you run yourself. Sync runs on its own, with no job to host.
Sync is one-way, from Orion to Git. Editing, reverting, or merging files in GitHub does not change anything in Orion.

Before you start

  • Tenant Admin: Only Tenant Admins can open the setup page. See Roles at a Glance.
  • Version control turned on for your workspace: If Admin Settings → Integrations has no Version control card, ask Gravity to turn it on.
  • A new GitHub repository with only a README: Create it on GitHub with Add a README file selected, and keep it for Orion. Orion refuses a branch that already has an orion.toml, ORION.md, or projects/ folder it did not create.
  • Repository access kept to admins: The repository receives every metric, view and Context page, including private ones. Give access only to the people who should see all of it.
  • A branch Orion can commit to directly: Orion commits straight to the branch you choose, without pull requests. Branch protection or a repository rule that blocks direct pushes stops the sync. Use a dedicated branch such as orion when your default branch is protected.

Connect a repository

1

Open the setup page

Go to Admin Settings → Integrations and open Version control. The page walks through four steps: Authenticate, Repository settings, Verify access, and Synchronization.
2

Authenticate

Choose an authentication method. Pick the Orion GitHub App where it is offered. Orion then stores no token at all: GitHub issues a short-lived one for each commit.
  • Orion GitHub App (recommended): Select Install on GitHub. A GitHub window opens, so allow pop-ups for Orion if your browser blocks it. Install the App on your personal account or organization and choose the repositories it can reach. The person who installs the App must be the one who connects it in Orion. Back in Orion, pick the repository from the list, which shows only repositories you can push to.
  • Personal access token (PAT): Enter the Repository URL and a token scoped to that repository with Contents read and write access. Orion encrypts the token and never displays it again.
Name the connection, then select Save connection and continue. A saved connection appears under Workspace connection the next time, so you can select Use saved connection instead of authenticating again.
3

Choose a branch

Enter the Branch. It must already exist, since Orion does not create branches. For a new repository with only a README, enter main. All existing and future projects use this repository and branch: there is no per-project setup. Select Save and verify access.
4

Verify access and enable

Orion checks that it can read the branch, then commits a small file, .orion/connection-check.json, to prove it can write. Read access and Write access both show Verified when the checks pass.Select Enable version control. If the repository was created without a README and has no commits, the button reads Initialize and enable version control, and Orion makes the first commit itself.
Orion then writes the folder structure: a folder for each project, plus the folders for catalog metrics and Context pages. The first pass commits every metric, view, catalog metric and Context page, every published dashboard, report, slide deck and HTML dashboard, and anything already set to Tracked in GitHub or Controlled. A large workspace is committed over several passes, a project at a time.

Choose what goes to GitHub

Every item in Orion keeps its versions in History, whatever its level. The level decides what else happens when the item changes: Tracked in GitHub is offered only while a repository is connected. Without one, items show Live edits and Controlled only.

Always tracked

Metrics, views, catalog metrics and Context pages are always Tracked in GitHub while a repository is connected. Their level menu offers Controlled, and shows Live edits greyed out with “Always tracked in GitHub”.

Where to set a level

Notebooks and Workflows have no level control of their own. A Workflow is committed when something it produces is tracked or published: a dashboard, an MDX report, a slide deck or an HTML dashboard. The notebooks it runs are committed with it. A notebook is also committed when a tracked dashboard uses it, and both are committed when their project is tracked.

Publishing

  • A dashboard or MDX report on Live edits is set to Tracked in GitHub when you publish it.
  • A slide deck or HTML dashboard is committed when you publish it. These have no level.
  • Unpublishing never takes anything out of GitHub. A slide deck or HTML dashboard that was committed keeps updating.
Every dashboard, report and slide deck belongs to a project, so each one is committed under its project’s folder.

What a level covers

  • A tracked project commits everything in it, including items added later: dashboards, MDX reports, metrics, views, notebooks, Workflows, and the Context pages linked to the project. A project can be tracked, but not Controlled. Items set to Controlled inside it stay Controlled.
  • A tracked dashboard also commits the metrics, views and notebooks it uses, and what those use in turn. Its menu says so before you change it.
  • A Controlled dashboard makes the metrics and views it uses need approval too. Their chip reads “Needs approval: used by” and the dashboard’s name.
  • A catalog metric is always tracked. Tracking a project or a dashboard that uses it changes nothing more.

Who can change a level

  • Live edits and Tracked in GitHub: anyone who can edit the item. Tracking a whole project needs admin capability on the project.
  • Controlled: only a Tenant Admin can make an item Controlled or take it off Controlled. A Group Admin can, too, for items whose projects belong only to the groups they manage.

Controlled items

A change to a Controlled item stays out of view until it is approved.
  • Dashboards and MDX reports: Save draft keeps your changes visible to you while viewers keep seeing the current version. Submit for review sends it for approval with a required note on what changed. Each Tenant Admin except the sender gets an Inbox item asking for a review.
  • Metrics and views: a change to the definition becomes a change request with a required note.
  • Context pages: every edit becomes a change request with a required note. The page’s creator, a Group Admin, or a Tenant Admin can approve it. Only a Tenant Admin or Group Admin can approve their own change.
Nothing reaches GitHub until the change is approved. The approved version is then committed like any other. History and Review covers drafts, review, history and restore.

What gets committed

Orion manages a fixed layout. Folder names are the item’s name in lowercase with a short ID after two dashes, so two items with the same name never collide.
reports/dashboards/, reports/mdx/, reports/slides/ and reports/pages/ appear once the first item of that kind in the project is committed. Credentials, query results, and notebook run logs are never committed. A data source is named, never its connection details.

When commits happen

Orion waits for edits to settle before it commits. An item’s changes go out 15 seconds after the last edit, and never more than a minute after the first. Edits that arrive while an item waits join the same commit. Each repository gets at most 200 commits an hour. A large first sync is grouped into a few commits, such as “Sync 12 projects and 40 dashboards from Orion”. Slide decks and HTML dashboards work a little differently. Publishing, renaming or unpublishing one is committed within about a minute. Changes to a deck’s or page’s content are picked up every 15 minutes, so several quick edits become one commit of the latest version.

Commit messages

While a dashboard has unsaved changes, the editor toolbar shows an optional What changed? field. Its text becomes the commit subject, up to 72 characters. Leave it blank and Orion writes a short summary of the change instead. The commit body names the dashboard and who changed it, in one of three forms:
  • “Weekly Revenue, edited by Ana Lopez in the dashboard editor.”
  • “Weekly Revenue, edited by Orion on behalf of Ana Lopez.” for a change made in chat
  • “Weekly Revenue, updated by Orion on a scheduled run.”
For other items, the subject is the note on the version, or a line such as “Updated metric Net Revenue”. The body lists each item with its version number and who edited it. GitHub attributes each commit to the Orion GitHub App or to the token’s owner, not to each editor. Use the commit body to see who made the change.

Renames, deletes, and going back to Live edits

  • Renaming an item or a project moves its files in the same commit. Renaming a catalog folder moves the files of the metrics in it.
  • Deleting a tracked item removes its files in a commit. Git history keeps every earlier version.
  • Setting an item back to Live edits leaves its files in the repository with their last committed version. They stop updating until you track the item again. Metrics, views, catalog metrics and Context pages cannot be set back to Live edits.

Check sync status

In the dashboard editor, the save status in the toolbar reports the GitHub commit as well as the Orion save. Select it for details, Check status, and a link to the files on GitHub. A dashboard on Live edits shows only its Orion save status. An item is always saved in Orion first, and a failed or pending commit never loses the save. History on a dashboard, report, metric or catalog metric lists each version with its commit, and links to that version on GitHub. On the setup page, the Synchronization step shows how many projects are synced, and how many items are pending or need attention. Branch health reports what Orion found on the branch at its last check. Orion checks once a day, more often while something is wrong. Select Check now to check straight away.

Fix items that did not sync

Each item that did not sync is listed on the setup page, with a link to it, the reason, and when Orion last tried it. Most problems clear without you: when GitHub does not confirm a commit, Orion checks and sends it again on its own. Orion stops retrying a problem that needs a person after about an hour. The item then reads “Orion stopped retrying. Fix it, then press Retry.”, and an Inbox item titled “Git sync stopped for” and the number of items appears. Fix the cause, then select Retry on the item. A rejected token, refused access, or branch protection pauses the whole sync, not one item. Those items carry no Retry: sync resumes once Orion verifies access again.

Files changed in GitHub

Other commits to the branch are fine. Do not edit or delete the files Orion manages. When Orion finds one changed or missing, it commits its own version on top, and an Inbox item says Orion restored its files. Git history keeps what was there. If someone commits to the branch while Orion is writing, Orion holds its change and writes it on top on its next pass.

Disconnect

Select Disconnect repository on the setup page. Orion stops committing, including any commits still pending. Files already in the repository stay there, and your items stay saved in Orion. The saved connection and its token are removed unless a project destination still uses them. Tracked items then show Live edits until a repository is connected again. To remove a saved connection you no longer use, open Workspace connection and select the X beside it. Files in the repository are not changed.

Important notes

  • One repository per workspace: Every project syncs to the same repository and branch.
  • Everything belongs to a project: Orion creates dashboards, reports and slide decks only inside a project. In a chat with no project selected, Orion asks you to select one first.
  • GitHub only: Other Git hosts are not supported.
  • One workspace per App installation: An Orion GitHub App installation serves one Orion workspace. A second workspace needs its own installation on a different account or organization.
  • History, not approval: A commit records a change that is already live in Orion. To require approval before a change goes live, set the item to Controlled.