Skip to main content
Use this page to diagnose common issues with Omni’s git integration. Each scenario describes what you’re seeing, why it happens, and how to fix it.

​
Branch not appearing in git

What you're seeing

You created a branch in Omni and made changes, but the branch doesn’t exist in your git repository.

Why it happens

Omni’s version control is separate from git. When you create a branch in Omni, it exists only inside Omni until you explicitly trigger a sync with your git repository. Omni only pushes a branch to git when you click Create pull request in the model IDE or update the branch through the Create or update YAML files API.

How to fix it

In the Omni model IDE, open your branch and click Create pull request. This triggers Omni’s backend to sync the branch to your git repository, at which point the branch will appear and you can open a pull request. If you’re working through the API, use the Create or update YAML files endpoint with a branchId — writing YAML to a branch syncs it to git the same way clicking Create pull request does.
The Create pull request button will be disabled until at least one model change is saved to the branch. Save a change before trying to sync.

​
Omni is creating branches from git PRs you didn’t initiate

What you're seeing

Omni is creating branches automatically whenever a PR is opened in your git repository, including PRs that weren’t started from the model IDE or API.

Why it happens

The Always create branches setting is enabled on your model (labeled Create Omni Branches for all pull requests in the IDE). When this is on, Omni creates a matching branch for every PR opened in git, regardless of whether it was initiated from the Omni IDE or API. For PRs that don’t include model changes, this creates empty Omni branches that can clutter your branch list.

How to fix it

In Omni, open your model in the IDE and navigate to Model > Git settings. Turn off Always create branches.Omni branches should always be initiated from the model IDE or API, not directly from git. With the setting off, Omni will only create a branch when you explicitly click Create pull request in the IDE or call the equivalent API endpoint.

​
Merge not reflected in Omni

What you're seeing

You merged a PR in git, but Omni doesn’t show the updated model or Omni pushed its own model state back to your base branch, overwriting the changes you merged.

Why it happens

Omni only reacts to pull request webhook events — opened, updated, and merged. It does not watch for direct pushes.Two things result in this scenario:
  • The PR was created outside of Omni. This happens when the PR was opened directly in git rather than initiated from the model IDE or API, so the branch has no corresponding Omni branch. When the merge webhook arrives, Omni looks for its branch, finds nothing, and pushes its current model state back to your base branch instead. This resets the base branch to Omni’s internal state and deletes any model YAML that was added only in git.
  • The change was pushed directly without a PR. A direct push or fast-forward to the base branch generates no PR webhook, so Omni is never alerted to the change.

How to fix it

For both cases, the fix is to make the change through an Omni branch:
  1. Create the branch in Omni
  2. Make your changes in the branch
  3. Click Create PR to sync the branch to git,
  4. Open and merge the PR through your git provider
Omni will receive the merge webhook, find its branch, and apply the changes.If the change is already on your base branch in git but not in Omni, re-create the change on an Omni branch and go through the PR workflow. Don’t try to restore the state by pushing to git directly, as Omni will overwrite it again on the next sync.
Omni treats its own model state as authoritative. If you push model YAML directly to your base branch, Omni will overwrite it the next time it syncs. See Corrective commit overwrites changes for the related scenario involving branches.

​
Corrective commit overwrites changes

What you're seeing

You made edits directly in the git repository on a branch — during a PR review, through an automated script, or through an external tool — and those changes were overwritten by a commit from Omni.

Why it happens

Every time Omni receives a PR webhook event, it pulls the branch from git and validates the YAML. If any file fails validation — due to invalid syntax, an unrecognized parameter, or improper indentation — Omni rejects the change and makes a corrective commit that restores the branch to its last known good state. The corrective commit appears in history with the author Omni Model Webhook Service. Git history is preserved, but any changes bundled with the bad YAML are also reverted.Omni rejects syntactically invalid YAML only. It accepts semantically broken code — for example, a join that references a field that doesn’t exist — but those problems will surface as model validator errors rather than triggering a corrective commit.

How to fix it

Make model changes through Omni, either in the IDE or through the Omni API, rather than editing the git repository directly. Omni validates changes at save time and gives you immediate feedback, so bad YAML never reaches the repository in the first place. If you need to make programmatic changes, use the Omni CLI or model APIs rather than committing to git.If you’re reviewing a PR and want to suggest a change to the YAML, make the edit in Omni on the branch. Once you save a change, the Update Pull request button will become active — click it to sync the corrected state to git.Non-model files committed to your repository are not affected by corrective commits or Omni’s model syncs. For example, CI configuration, scripts, or root-level ownership files.However, nested metadata files placed inside model subdirectories (for example, OWNERS.yaml files under omni/<model>/) may be removed when Omni regenerates its projection. If you’re using code ownership tooling, keep those files at the root of your omni/ directory rather than nested inside model folders.
If you’re using automation or an AI agent that interacts with your git repository, redirect it to use the Omni APIs instead. Agents that commit directly to git will reliably trigger corrective commits whenever their output contains a YAML error. See Omni agent skills for more information.

​
Merging a PR reverted changes from another branch

What you're seeing

You merged a pull request and changes that were previously merged from a different pull request disappeared from the shared model. In the model IDE’s model history, the Webhook merge entry for the PR shows a diff that changes files the PR didn’t touch in git — for example, a re-uploaded CSV reverting to older data or fields added by an earlier merge being removed.

Why it happens

When a pull request merges, Omni doesn’t apply git’s merge result to the shared model. Instead, it promotes the Omni branch associated with the PR: every model file stored on that branch is applied on top of the current shared model, replacing the shared version of those files. The most recently merged branch wins, file by file.An Omni branch only re-syncs from git when new commits are pushed to its open PR. If a PR sits open while other PRs merge, its Omni branch keeps the older state of any files it carries. Merging it then overwrites the newer shared model state for those files, even if the PR’s git diff never touched them.Because Omni treats its own model state as authoritative, it also pushes the post-merge state back to your base branch. The revert lands in git too, even though git’s own merge of the PR was correct.

How to fix it

To recover the lost changes, re-apply them through Omni by either redoing them on a new branch or by restoring the affected files from a version prior to the merge. Don’t attempt recovery by pushing YAML directly to git. See Recovering from a broken model state for the restore steps.To prevent this from happening:
  1. Update stale PRs before merging them. Push a new commit to the PR branch or merge the base branch into it (for example, GitHub’s Update branch button). This sends Omni a webhook that re-syncs the Omni branch against the current shared model. Alternatively, open the branch in the model IDE, save a change, and click Update pull request.
  2. Keep branches short-lived. The longer a PR stays open while other changes merge, the more likely its Omni branch is carrying stale copies of shared files.
  3. Review the merge in model history. After merging a long-lived PR, open the model history and check the Webhook merge entry’s diff. If it changed files the PR shouldn’t have touched, restore or re-apply promptly.

​
Webhook misconfiguration

What you're seeing

Omni isn’t reacting to PRs in your git repository. This includes not creating branches in Omni when PRs are opened and not reflecting merged changes in the shared model.

Why it happens

Omni relies entirely on PR webhooks from your git provider. If the webhook isn’t configured correctly, Omni never receives the events it needs. Common misconfiguration causes:
  • Wrong content type: The webhook content type must be set to application/json. This mainly affects GitHub, where new webhooks default to application/x-www-form-urlencoded — Omni can’t parse payloads sent with that content type. Other providers send JSON payloads by default; see your provider’s setup guide for the exact webhook configuration.
  • Wrong event types: The webhook must be configured to send pull request events only. Push events should be turned off — Omni doesn’t react to them, and leaving push events enabled adds noise without benefit.
  • Wrong payload URL: The payload URL must reference your specific Omni model ID. If the model ID in the URL doesn’t match the model you’re trying to integrate, events will be ignored.
  • Wrong or missing webhook secret: The webhook secret in your git provider must match the secret generated by Omni during setup. A mismatch causes Omni to reject incoming events.

How to fix it

In Omni, open your model in the IDE, navigate to Model > Git settings, and locate the git configuration section. Cross-check each value against what’s configured in your git provider:
1

Confirm the payload URL

Verify the payload URL contains the correct model ID.
2

Confirm the content type

The content type must be set to application/json.
3

Confirm the event types

Only pull request events should be selected. Disable push events.
4

Confirm the webhook secret

The webhook secret must match the value shown in Omni.
After updating your webhook, use the Test git connection button in Omni’s git settings to verify connectivity.
This button tests the deploy key connection; it does not validate the webhook configuration itself. To confirm webhook delivery, check the Recent Deliveries log in your git provider’s webhook settings. A failed delivery with a signature verification error indicates a webhook secret mismatch.

​
Schema refresh commits on default branch

What you're seeing

Omni is committing directly to your base branch (for example, main) outside of the PR workflow. This may conflict with branch protection rules that require PRs for all changes to the base branch.

Why it happens

By default, certain Omni actions — schema refreshes, API events, and model syncs — commit directly to your base branch without going through a pull request. Omni fetches the latest commit, then pushes the regenerated model directly on top using a normal commit, not a force push. If your repository has branch protection rules that require PRs for all changes to the base branch, this direct commit will conflict with those rules.Manual changes you make directly to model YAML on the base branch may also be overwritten the next time one of these syncs runs, since Omni regenerates the full model state when it writes. Non-model files in the repository are not affected.

How to fix it

There are three approaches. Pick the one that fits your team’s workflow:
  • Use Option 1 if you need to satisfy strict branch protection rules with no bypass exceptions.
  • Use Option 2 if you want schema refreshes to stay direct while keeping human developers gated behind pull requests.
  • Use Option 3 if you want to keep Omni’s writes off your protected main branch entirely.
In Model > Git settings, enable the Pull request required toggle, then enable its Require for system syncs sub-setting. This routes schema refreshes and other system-generated commits through the branch and PR workflow, satisfying strict branch protection requirements with no exceptions needed.
Branch-based schema refresh must be enabled before you can enable Require for system syncs.Branch-based schema refreshes can’t be enabled for connections with more than one model. The tradeoff is that schema changes appear in PRs alongside model changes, which can make reviews less focused.
Switch Omni’s git credentials from the default SSH deploy key to HTTPS token authentication using a token that belongs to a dedicated machine user, then add that machine user to your branch protection rule’s bypass list. This keeps schema refreshes direct and low-friction while leaving all human developers gated behind pull requests.
HTTPS token authentication is only available for GitHub and GitLab. If you’re using Azure DevOps or Bitbucket, use Option 1 or Option 3 instead.
In Model > Git settings, set the Base branch field to a branch that isn’t your protected main — for example, omni-prod — and leave that branch unprotected.Omni’s pushes land there without issue and main is never touched.
Omni never force-pushes your base branch. The applicable branch protection rule in this scenario is “require a pull request before merging,” not “restrict force pushes.” Clarifying this with your platform team early can prevent the force-push concern from blocking setup.

​
Follower not picking up changes

This scenario applies to models configured with git follower mode.

What you're seeing

You merged a change to your follower’s watched branch in git, but the follower’s model hasn’t updated.

Why it happens

There are two potential causes:
  1. Changes were made without going through a PR merge. Like the leader, a follower only reacts to PR merge events on the branch it’s configured to watch. If a change was pushed or committed directly to that branch without going through a PR merge, the follower won’t detect it.
    If you’re using a release branch as a validation step before merging to your follower’s watched branch, make sure the PR targets the correct watched branch. A PR merged to main won’t trigger a follower that’s watching a prod branch.
  2. Schema mismatches between the leader and follower schema model. The follower reconciles the git projection against its own schema model to determine what belongs in the shared layer. If the follower’s database schema differs from the leader’s, the follower may accept the change but surface errors when users query topics that reference fields missing from its schema. For example, tables are missing or are named differently.

How to fix it

  • To resolve an event trigger issue, confirm the change reached the follower’s watched branch through a PR merge. If you pushed directly, open a PR from that branch to the watched branch and merge it.
  • To resolve a schema mismatch issue, verify that the database schemas on the leader and follower are identical. The follower needs to be able to account for every field referenced in the git projection using its own schema model. If schemas have diverged, run a schema refresh on the follower after confirming the underlying database matches, then trigger the follower by merging a PR to its watched branch.

​
Recovering from a broken model state

What you're seeing

Your Omni model is in a broken state and you need to restore it to a known good state. For example, dashboards aren’t loading, topics are missing, or a schema refresh has removed a large portion of your views.

Why it happens

Omni is the source of truth and git is a projection of Omni’s state. This means you can’t restore Omni by pushing the correct YAML to git, as Omni will overwrite whatever you push the next time it syncs.

How to fix it

Don’t attempt recovery by pushing or restoring YAML directly in git. Omni regenerates its projection from its internal model state, so git-only changes will be overwritten. The steps below are the only correct recovery path.
The correct recovery path is through Omni’s own model history:
  1. In Omni, open your model in the IDE.
  2. Click the icon in the left navigation.
  3. Find the entry that represents the last known good state, then restore to that version.
  4. Once Omni’s model state is correct, it will push that state to git on the next sync, bringing the repository back into alignment.

​
Git authentication failed

What you're seeing

You receive a "Git authentication failed" error when Omni attempts to connect to your git repository.

Why it happens

This error indicates an issue with your access token. Common causes:
  • Expired or revoked tokens
  • Insufficient permissions
  • Incorrect token format, including a partial token, extra characters, or whitespaces

How to fix it

  1. Confirm your token is still valid. If the token has expired or been revoked, generate a new one with the appropriate permissions.
  2. Verify the token’s permissions. The following permissions are required:
    • GitHub - Contents (read and write), Metadata (read-only), and Pull requests (read and write)
    • GitLab - api, read_repository, and write_repository scopes
  3. Check the token’s formatting. Ensure you’ve copied the entire token without any extra spaces or characters.
If you created a new token, you’ll also need to update the token in Omni:
  1. Open your model in the IDE.
  2. Navigate to Model > Git settings.
  3. Click Change token.
  4. Enter the new token and save.

​
Git push rejected

What you're seeing

You’re receiving the following error in Omni:

Why it happens

This error occurs when Omni tries to commit directly to your base branch but your repository has branch protection rules that block direct pushes.

How to fix it

See Schema refresh commits on default branch for the three options that resolve this conflict.