> ## 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, Azure DevOps) 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, GitLab or Azure DevOps from the integrations page.

1. Navigate to **Admin > Integrations**
2. Find the card for your preferred provider (GitHub, GitLab or Azure DevOps)
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

### Connecting Azure DevOps

Connecting Azure DevOps lets BRMS push to Azure Repos and trigger Azure Pipelines from [webhooks](/brms/setup/webhooks). For the Entra ID app registration walkthrough and server-side details, see [Git integrations](/developers/deployment/brms/integrations#azure-devops-configuration). Two connection methods are available:

| Method | When to use |
| - | - |
| **Service Principal** | Recommended for Azure DevOps Services - a machine identity that does not expire with a user |
| **Access Token** | A Personal Access Token. The only option for Azure DevOps Server, but tied to a user and subject to expiry |

Both methods require the **Organization URL**: `https://dev.azure.com/<organization>` for Azure DevOps Services, or your collection URL for Azure DevOps Server.

#### Service Principal

1. Register an application in Microsoft Entra ID and create a client secret
2. In Azure DevOps, go to **Organization settings > Users** and add the application as a member
3. Grant it access to the projects and repositories it should reach
4. In BRMS, fill in the connection form:

| Field | Description |
| - | - |
| **Directory (tenant) ID** | From your Entra ID tenant |
| **Application (client) ID** | From the app registration |
| **Client secret** | The secret created for the app registration |

#### Access Token

1. Create a Personal Access Token in Azure DevOps (**User settings > Personal access tokens**) with the following scopes:
   * **Code**: Read & write
   * **Build**: Read & execute
2. Paste the token into the connection form and click **Connect**

<Note>
  GitLab and Azure DevOps 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 these providers.
</Note>

<Warning>
  Azure Repos creates repositories empty. Push an initial commit to the target repository before enabling Git Sync on it.
</Warning>

## 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, GitLab or Azure DevOps 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. For Azure DevOps, verify the service principal or token owner has access to the Azure DevOps project that contains the repository.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.