TL;DR. Motley’s GitHub integration lets you store your semantic models in a repo. It gives you:
- Auto-import from the default branch
- Validation of proposed changes inside pull requests, as a check
- Checking out a working branch just for yourself , so you can test before merging
- Editing from inside Motley, committed back to your working branch
- A safe, governed way to use AI agents for maintaining the semantic layer itself
Motley’s GitHub integration allows data teams to store their models in a GitHub repo. The state of the default branch becomes the source of truth for the models. On push, the Motley app imports the configs immediately and propagates them to every consumer within a few seconds.
One of the main reasons to run a semantic layer is to have a single governed place where human-approved canonical definitions are stored and managed, and that is exactly what Git is good at.
If you (or your agent) want to change a definition, add a model, or add a memory, you open a pull request. Just as with any other code, you can require checks to pass, require approvals from specific people before merging, and everything else you already do in the GitHub UI. Once the PR is merged, the source of truth is updated. Before merging, you also want to know that the configs are actually valid. Otherwise the import from the default branch fails, or worse, queries start failing in production. So the Motley app validates the new configuration inside the PR itself. It checks that the models are set up correctly, and it can optionally validate your definitions against the data source.
Testing the edits #
Valid is not the same as correct. When you work on the semantic layer you want to test it as well: connect an agent and ask it questions, or run a full eval suite against it.
How do you do that without disturbing everyone else? Motley lets you check out the working branch just for yourself. The rest of the team stays on the default branch.
Every agent connected to your account now sees the updated semantic layer. Once you are satisfied, you merge the PR and the changes become available to everyone.
This is an admin-only feature. Regular users always stay on the default branch.
Editing via Motley #
One of the core principles of Motley is being MCP-first, and that includes management operations. Model editing is available to admins over MCP. With GitHub connected, the default branch is read-only, because we only sync configs from GitHub and never the other way around. So how do admins update the semantic layer through their agents?
When you are on a non-default branch, editing is allowed. Every change is committed by Motley under your name to your working branch as it happens. That makes it practical to hand an agent, even a long-running one, nothing but the MCP server and let it maintain the layer. The same agent can run evals by spawning subagents, and they all stay on the same branch.
When you are done, you open a PR and merge it into the default branch as usual, and your edits propagate to the rest of the team.
Keeping your models together #
If you are reading this, odds are you already have a data stack, and probably a GitHub repo holding its configuration: dbt transformations, dashboard configs, and the rest. It makes sense to keep your Motley models and memories in that same repo, so Motley lets you specify the directory they should live in. You can then update your dbt configs and the related Motley models in a single pull request, which keeps the change transactional.
For more on what belongs in those configs, see why a semantic layer is more than a database schema and why your semantic layer needs memory.