Git integration
Connect a Forge project to an external GitHub repository to mirror your CML as committed files — optional, and never required for saving.
When to use it — When you want a copy of your semantic model in version control, or to feed CML changes into your own GitHub review and CI processes.
Where to find it — Open a project in Forge, then Project settings → Version history → Connect Git repo.
Who can use it — Weaver and Luminary.
Forge already keeps a full history of your model for you: every save creates a version automatically. Git integration is a separate, optional layer on top of that. When you connect a repository, Forge can write your nodes and domains into that repo as files, commit them, and open a pull request against your default branch — useful if your team already lives in GitHub.
Git integration never affects whether a save succeeds. You do not need a repository connected to build, validate, or save your model. If you skip this feature entirely, nothing in Forge changes.
Overview
Git integration is configured per project, not per workspace. Each project can connect to one external repository. The connection stores:
- The provider (GitHub).
- The repository URL.
- A default branch (defaults to
main). - An access token, which is encrypted at rest and only ever shown back to you masked (for example
ghp_••••••••••••AbcD). - Two behavior flags: auto PR and require review.
Once connected, Forge can perform three actions against the repository: take a snapshot of your model's status, commit selected node and domain files to a branch, and open a pull request from that branch into your default branch. Forge writes each node or domain to a file named after the node or domain itself, then commits and pushes.
Saving and validation in Forge are handled entirely by the Check & Save gate and version history — they run whether or not Git is connected. Connecting Git adds an export path; it does not replace or gate the save flow.
When to use it
Connect a repository when you want one or more of the following:
- A copy of your CML in your own GitHub repository, so it lives alongside the rest of your code.
- Pull requests on GitHub so your existing reviewers and branch-protection rules apply to model changes.
- A trigger point for your own CI (your GitHub Actions run on the PR Forge opens).
If you only need to undo a change or look at what the model looked like last week, you do not need Git — use Forge's built-in version history instead. Git is for teams that specifically want their semantic model mirrored into source control.
Concepts
| Term | What it means |
|---|---|
| Provider | The Git host. GitHub is the supported provider — it gets a live connection test and pull-request creation. |
| Repository URL | The HTTPS URL of the repo Forge writes to, e.g. https://github.com/acme/celiq-model. |
| Default branch | The branch pull requests target. Defaults to main. |
| Access token | A personal access token Forge uses to authenticate. Stored encrypted; never displayed in full after you save it. |
| Commit | Forge writes the selected nodes/domains to files on a branch and records a commit (then pushes it). |
| Pull request | Forge opens a PR on GitHub from your working branch into the default branch. |
| Auto PR | A saved preference to open a pull request after committing rather than stopping at the commit. |
| Require review | A saved preference indicating model changes should go through PR review before they land on the default branch. |
Getting started
Prerequisites:
- A Forge project you can edit (Weaver or Luminary).
- A GitHub repository you can push to.
- A GitHub personal access token with permission to read the repo, push commits, and open pull requests.
To open the settings:
Open the project in Forge
Go to Forge and open the project you want to connect.
Open Project settings
Open Project settings for that project. Scroll to the Version history section.
Start the Git connection
Click Connect Git repo. Note the reminder shown there: "Git is optional and has no impact on saving or validation."
Step-by-step
Enter the repository details
Provide the provider (GitHub), the repository URL (for example https://github.com/acme/celiq-model), and the default branch (leave as main unless your repo uses a different one).
Paste an access token
Paste a GitHub personal access token that can push to the repo and open pull requests. Forge encrypts it before storing it, and afterwards only shows it back masked.
Test the connection
Run the connection test. For GitHub, Forge calls the GitHub API and confirms with a message like "Connected to acme/celiq-model · main branch found". If the token or URL is wrong, it returns the error GitHub reports (for example a permissions or not-found message).
Set your preferences
Choose whether to enable auto PR (open a pull request after committing) and require review (changes should go through PR review). These are saved with the connection.
Save the connection
Save. The configuration is now attached to this project. You can return to Project settings later to update the URL, branch, token, or flags, or to remove the connection entirely.
Commit your model
When you want to mirror changes, commit the affected nodes and domains to a branch with a commit message. The message must be at least 3 characters. Forge writes each selected node or domain to a file, commits, and pushes to the branch.
Open a pull request
To propose the branch into your default branch, open a pull request with a title (and optional description). Forge creates the PR on GitHub and returns its URL and number so you can review and merge it there.
Examples
A realistic shape for the connection you set up in Project settings:
{
"provider": "github",
"repo_url": "https://github.com/acme/celiq-model",
"default_branch": "main",
"auto_pr": true,
"require_review": true
}When you commit, each selected node or domain is written as its own file using the node or domain name, then committed with your message:
Commit on branch: forge/orders-update
Message: "Add net revenue metric to orders"
orders.yml (modified)
customers.yml (modified)
→ pushed to origin/forge/orders-updateOpening a pull request from that branch into main returns a link you follow to GitHub to finish review and merge:
PR #128 opened: forge/orders-update → main
https://github.com/acme/celiq-model/pull/128Best practices
- Keep Git as a mirror, not a gate. Treat the connection as a way to export your model. Continue to rely on Forge's Check & Save gate and version history for day-to-day safety.
- Scope your token tightly. Use a token that can reach only the one repository you connect, with just the permissions needed to push and open PRs.
- Commit related changes together with a clear message so the resulting GitHub diff is easy to review.
- Use a working branch, not the default branch, for commits so your default branch only changes through reviewed pull requests.
- Re-run the connection test after rotating a token or changing the repository URL so you catch problems before you try to commit.
Tips
Your access token is encrypted before it is stored and is only ever returned to you masked. If you ever need to change it, paste a new token and save — Forge keeps the existing one if you leave the field blank, so you do not have to re-enter it just to change the branch or a flag.
Common mistakes
- Expecting Git to control saves. It does not. Saving and validation run through the Check & Save gate regardless of whether Git is connected.
- Using a non-GitHub URL and expecting a PR. Pull-request creation is GitHub-only. A non-GitHub repository will fail with "Only GitHub repos are supported for PR creation."
- Committing with a one- or two-character message. Commits require a message of at least 3 characters and are rejected otherwise.
- Using a read-only token. If the token cannot push or open PRs, the connection test may still pass for a read check but commits and PRs will fail.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| "Could not connect" on the connection test | The token is invalid/expired or lacks access to the repo | Generate a new token with access to the repository and test again. |
| Test reports the repo cannot be found | The repository URL is wrong or the token cannot see that repo | Confirm the URL points at the exact owner/repo and that the token has access. |
| "Git not configured for this project" when committing or opening a PR | No Git connection is saved for this project | Open Project settings → Connect Git repo and save a configuration first. |
| "Commit message required (min 3 chars)" | The commit message is empty or shorter than 3 characters | Enter a descriptive message of at least 3 characters. |
| "Only GitHub repos are supported for PR creation" | A pull request was requested for a non-GitHub repository | Use a GitHub repository, or finish the merge manually in your own provider. |
| "PR title required" | A pull request was requested without a title | Provide a title (and optionally a description) and retry. |
| Nothing appears in the new commit | No selected file had changes to write | Make sure the nodes or domains you selected actually changed, then commit again. |