> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gorules.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Git Sync

> Automatically synchronize your project decisions to a Git repository.

Git Sync automatically creates a Pull Request (GitHub) or Merge Request (GitLab) in your repository whenever you merge branches or commit to the main branch in BRMS. This keeps your Git repository in sync with your decision files.

## Prerequisites

Before enabling Git Sync on a project, an organization administrator must connect a Git provider. For self-hosted deployments, the provider must first be configured at the server level — see [Git integrations](/developers/deployment/brms/integrations).

## Connect a Git provider

Organization administrators can connect GitHub or GitLab from the integrations page.

1. Navigate to **Admin > Integrations**
2. Find the card for your preferred provider (GitHub or GitLab)
3. Click **Connect**

### Connecting GitHub

1. Click **Connect to GitHub**
2. If the GitHub App is already installed on your account, select which organization to connect
3. If not installed, you'll be redirected to install the GitHub App — choose which repositories to grant access to
4. Complete the authorization

### Connecting GitLab

1. Fill in the connection form:

| Field              | Description                                  |
| ------------------ | -------------------------------------------- |
| **GitLab URL**     | `https://gitlab.com` or your self-hosted URL |
| **Application ID** | From your GitLab OAuth application           |
| **Secret**         | From your GitLab OAuth application           |

2. Click **Connect to GitLab**
3. Authorize the application in GitLab
4. You'll be redirected back to BRMS

<Note>
  GitLab credentials are encrypted and stored securely using your organization's secrets provider. For self-hosted deployments, [secrets management](/developers/deployment/brms/secrets-management) must be configured before connecting GitLab.
</Note>

## Enable Git Sync on a project

Once a Git provider is connected, project managers can enable Git Sync for individual projects.

1. Navigate to **Project Settings > Git Sync**
2. Toggle **Enable Git Sync** to on
3. Configure the sync settings:

| Setting           | Description                                           |
| ----------------- | ----------------------------------------------------- |
| **Git Provider**  | Select your connected provider                        |
| **Repository**    | Choose the target repository                          |
| **Target Branch** | Branch to create PRs against (defaults to `main`)     |
| **Path**          | Subdirectory for synced files (e.g., `rules/pricing`) |

4. Click **Save Configuration**

<Warning>
  You must specify a subdirectory path. Syncing to the repository root is not allowed.
</Warning>

## How Git Sync works

When you merge a branch in BRMS:

1. A new branch is created in the Git repository (e.g., `commit-abc12345`)
2. All decision files from your project are committed to the configured path
3. A metadata file is included with sync information
4. A Pull Request or Merge Request is automatically created against your target branch

### Synced file structure

```
your-repository/
└── {configured-path}/
    ├── .config/
    │   └── project.json      # Sync metadata
    ├── decision-table.json
    ├── rule-flow.json
    └── ...                   # All project decision files
```

### Project metadata

Each sync includes a `.config/project.json` file with metadata:

```json theme={null}
{
  "version": "1",
  "project": {
    "id": "project-uuid",
    "key": "project-key"
  },
  "commit": {
    "id": "commit-uuid",
    "message": "Merge branch feature into main",
    "branchName": "main"
  },
  "sync": {
    "syncedAt": "2024-01-15T10:30:00.000Z"
  }
}
```

## Sync status

After a merge, the commit history shows a sync status badge:

| Badge | Status  | Description                        |
| ----- | ------- | ---------------------------------- |
| Blue  | Pending | Sync is in progress                |
| Green | #123    | PR/MR created (click to view)      |
| Red   | Failed  | Error occurred (hover for details) |

## Permissions

| Action               | Required permission              |
| -------------------- | -------------------------------- |
| Connect Git provider | Organization Administrator       |
| Configure Git Sync   | Project Manager (Manage Project) |
| View sync status     | Any project member               |

## Troubleshooting

### "No Git integration configured" warning

No Git provider is connected to your organization. Contact your organization administrator to configure a GitHub or GitLab integration in **Admin > Integrations**.

### Sync status shows "Failed"

Hover over the red badge to see the error message. Common causes:

* Repository access was revoked
* Target branch no longer exists
* Network connectivity issues

### Sync stays "Pending" for more than 5 minutes

If a sync shows "Pending" for an extended period, it may have failed silently. The status will eventually change to "Sync timed out". Check your Git provider to see if a PR was partially created.

### Cannot see repositories in dropdown

The connected Git provider account may not have access to the repository you're looking for. For GitHub, verify the GitHub App is installed on the organization that owns the repository. For GitLab, verify the connected user has access to the repository.