Maia Git Integration: Hosted vs. Third-Party Git, and How Context Files Keep Commits Consistent

You pick your git setup once, when you create a project. Pick the wrong one and you either outgrow it in a quarter or spend a week on setup you didn't need.

Maia builds git into the Designer interface, so versioning, collaboration, and commits happen where you build pipelines. You don't install or maintain a local copy of anything. The first decision is where your repository lives. The second is how you work with branches and commands once it's set up. The third is how you keep every commit consistent without restating the same rules in every prompt.

This post covers all three, plus the limits to know before you commit to a setup.

Maia-hosted git vs. third-party git

When you create a project, you choose between two paths.

Maia managed. The platform hosts and manages your git repository, secrets manager, and Runner. Choose this if you want to get set up quickly.

Advanced settings. You mix and match your repository hosting and your deployment. Choose this if you want more flexibility. Inside advanced settings, you pick Maia-hosted git or connect your own.

When Maia-hosted git fits

With Maia-hosted git, we host the repository for you. Either route that uses Maia hosting (Maia managed, or Advanced settings with Maia Hosted Git) creates a repository with a default branch called main.

It suits one- or two-person data teams with relatively simple git workflows. There's nothing to provision, and you're versioning pipelines from day one.

When to connect your own git

Larger or cross-functional teams with more complex workflows usually need the third-party option. Maia integrates with your organization's git provider: GitHub, Azure DevOps, GitLab, or Bitbucket.

Your pipelines stay under the same centralized control as the rest of your code, and you get your provider's more advanced features:

• Pull requests
• Branch protection rules
• Access to your existing CI/CD tooling

Connecting your own git requires the Maia app installed in your organization's account with your provider. Some details to check first:

• The GitHub app supports GitHub only. GitHub Enterprise Server isn't supported.
• Customer-hosted git repositories are available through Hybrid SaaS deployments. Full SaaS deployments use a Maia-hosted repository.
• This feature is only available on specific Maia plans, so check pricing.

One decision you can't undo

Once you connect a project to a git repository, you can't disconnect it or point it at a different one. You can't switch from GitHub to GitLab, for example. If you need to, you create a new project from scratch. Reusing an existing Matillion ETL git repository isn't supported either.

That makes the hosted-versus-third-party call worth five minutes of thought up front. Connecting a repository doesn't require an environment or data warehouse connection to exist first, so you can make the choice early.

Quick comparison

Git basics in Maia: branches and the branch menu

Picture a data team building pipelines together. More than one person needs to work on the same set of pipelines, often at the same time, without breaking what's already running in production. Git closes that gap. It gives every change a record and gives the team a way to bring that work back together safely.

Start with a branch

When you start a new project, your first branch, main, is created for you. From there you create other branches to work on. Maia recommends feature branching: one branch per piece of work. Branch from main, name the branch for the feature, and select your default environment for it.

A branch is not a copy of your project. It's a pointer to a commit: a label that marks a point in your project's history and moves forward as you add commits on top of it. Think of a book. The book is your project and each page is a commit, a saved point in the story. Creating a branch doesn't clone or back up the project. It drops a new bookmark at the commit you're standing on, ready to track whatever you add from there.

The branch menu

Everything else lives in the branch menu. Once you're working on a branch, you have these commands:

Two behaviors catch new users out. Until you push, your commits exist only in your own working copy. Your teammates won't see them until you've pushed to the remote and they've pulled from it. And merging runs from the destination: with feature branching, you go to main and merge the finished feature branch into it.

A day-to-day git workflow in Designer

Put together, the working pattern is the same whichever setup you chose. Develop on branches other than main (or your repository's equivalent) and merge when the work is finished.

1. Open a branch. Click the branch you want to check out from your project. Designer opens with that branch loaded.
2. Build your pipelines. Your changes exist locally on that branch until you commit them.
3. Commit. Open the git menu from the branch name at the top of the page and click Commit changes. Add a commit message (optional in the UI) and click Commit.
4. Push. Click Push local changes, then Push. Teammates can now pull your changes.
5. Merge to main. Switch to main, click Merge from branch, select the remote branch you built on, and click Merge.
6. Publish and schedule. Publishing is only permitted on main, which is another reason to merge finished work there.

You can also ask Maia to run these git operations for you, which is where context files come in.

Security checklist if you host your own repository

If you connect your own git, a few practices matter:

1. Authenticate securely. Use HTTPS and strong credentials.
2. Set granular access controls. Only authorized users should have write access.
3. Encrypt data in transit. This covers data moving between Maia and your repository.
4. Test your backups. Back up repositories regularly, including repo content and metadata such as pull requests, and confirm you can restore them.

Use context files to standardize git operations

Context files are markdown files stored in your project. They embed reusable knowledge into every Maia prompt. You can include:

• Project context
• Business rules
• Data warehousing standards
• Naming conventions

Define your standards once and Maia follows them every time. You stop repeating requirements in each prompt.

Where context files live

Context files must be .md files stored in .matillion/maia/rules/. Designer creates the folder automatically when you add a context file through the Maia interface. If you create one from scratch, create the folder structure first. You can find the folder in the Files panel in Designer.

Two limits to plan around:

• Maia enforces a 12,000-character limit across all markdown files in .matillion/maia/rules/.
• Additional context files stored elsewhere in your project don't count toward that limit. Maia ignores them unless you reference them, for example with @naming-conventions.md in your prompt. Keep these outside the .matillion/ folder, which is reserved.

Because the files live in your repository, they travel with your branches. Follow the recommended git workflow for context files so they're shared properly across branches, and review them regularly. Maia won't prompt you to update them unless you ask.

Example: commit message format

Say your team wants commit messages in a specific format. Put that format in a context file. A rule might look like this (example only, adapt to your team):

## Commit messages
- Start with the pipeline type: [orchestration] or [transformation].
- Follow with a short imperative summary under 72 characters.
- Reference the ticket ID in brackets at the end, e.g. [DATA-123].

When you ask Maia to commit changes in your pipeline, it builds the commit message and follows the conventions you set. You don't restate them for each git operation. For a team, that gives you the same commit history regardless of who asked Maia to commit.

Troubleshooting

If Maia doesn't follow your standards, check three things: the file sits in .matillion/maia/rules/, it's within the character limit, and the rules are written as clear directives ("Start with…", not "It would be nice if…"). You can also reference the standards explicitly in your prompt.

What Maia can and can't do in git

Maia can generate commit messages, commit changes, pull changes from remote, and push to a branch. It can also show you uncommitted changes and diffs so you can review work before committing.

It can't perform advanced git operations such as creating branches, resolving conflicts, or managing pull requests. Use Designer's branch menu or your git provider for those.

Cherrypicking isn't supported in Maia at all. If your project uses a repository on GitHub, GitLab, Azure DevOps, or Bitbucket, cherrypick with your host's UI or CLI tools. Maia-hosted repositories don't support it.

Get started

Create a project, choose your git setup, and add a context file with your commit message format. Then branch from main and ask Maia to commit your next pipeline change.