> ## 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 integrations

> Configure GitHub, GitLab and Azure DevOps integrations for Git Sync and webhooks in self-hosted deployments.

Git Sync and Git-based [webhooks](/brms/setup/webhooks) require integration with a Git provider (GitHub, GitLab or Azure DevOps). This guide covers the server-side configuration for self-hosted BRMS deployments.

<Info>
  For instructions on connecting and using Git Sync from the BRMS interface, see [Git Sync](/brms/setup/git-sync).
</Info>

## Prerequisites

Before configuring Git integrations, ensure you have:

1. A running BRMS instance with a publicly accessible URL (required for OAuth callbacks)
2. [Secrets management](/developers/deployment/brms/secrets-management) configured (required for GitLab and Azure DevOps)

## Required environment variables

All provider integrations require these environment variables. Set them before proceeding with provider-specific configuration.

```bash theme={null}
# Your BRMS instance URL (used for OAuth callbacks)
APP_URL=https://brms.yourcompany.com

# Secret for signing OAuth state tokens (min 32 characters)
# Generate with: openssl rand -hex 32
APP_INTEGRATIONS_SECRET=your-random-secret-minimum-32-characters
```

| Variable | Description |
| - | - |
| `APP_URL` | Your BRMS instance URL |
| `APP_INTEGRATIONS_SECRET` | Secret for signing OAuth state tokens (min 32 characters) |

## GitHub configuration

GitHub integration uses a GitHub App for authentication and repository access.

### Step 1: Create a GitHub App

1. Go to **GitHub > Settings > Developer settings > GitHub Apps**
2. Click **New GitHub App**
3. Fill in the required fields:

| Field | Value |
| - | - |
| **GitHub App name** | Choose a unique name (e.g., "YourCompany BRMS") |
| **Homepage URL** | Your BRMS instance URL |
| **Callback URL** | `{APP_URL}/api/app-integrations/github/callback` |

### Step 2: Configure permissions

Under **Repository permissions**, set:

| Permission | Access Level |
| - | - |
| Contents | Read & Write |
| Pull requests | Read & Write |

### Step 3: Configure installation settings

1. Check **Request user authorization (OAuth) during installation**
2. Under "Where can this GitHub App be installed?", choose:
   * **Only on this account** - For single organization use
   * **Any account** - If multiple organizations will use the integration

### Step 4: Generate credentials

After creating the app:

1. Note the **App ID** at the top of the settings page
2. Note the **Client ID** in the app settings
3. Generate a **Client Secret** and save it
4. Scroll to **Private keys** and click **Generate a private key**
5. Download the `.pem` file and Base64 encode it:

```bash theme={null}
base64 -i your-app-name.private-key.pem
```

### Step 5: Set GitHub environment variables

```bash theme={null}
# GitHub App credentials
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY=LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQo...
GITHUB_APP_CLIENT_ID=Iv1.abc123def456
GITHUB_APP_CLIENT_SECRET=your_client_secret_here

# GitHub App installation URL (found in app settings under "Public link")
GITHUB_APP_INSTALL_URL=https://github.com/apps/your-app-name/installations/new
```

## GitLab configuration

GitLab integration uses OAuth 2.0 and supports both GitLab.com and self-hosted instances.

<Warning>
  GitLab integration requires [secrets management](/developers/deployment/brms/secrets-management) to be configured. GitLab credentials (Application ID and Secret) are encrypted and stored using your configured secrets provider. Without secrets management, GitLab integration cannot be enabled.
</Warning>

### Step 1: Create an OAuth application

Navigate to your GitLab instance and create an application at one of these locations:

| Location | Use case |
| - | - |
| **User Settings > Applications** | Personal use |
| **Group Settings > Applications** | Organization/group use |
| **Admin Area > Applications** | Instance-wide (self-hosted only) |

### Step 2: Configure the application

| Field | Value |
| - | - |
| **Name** | BRMS Integration |
| **Redirect URI** | `{APP_URL}/api/app-integrations/gitlab/callback` |
| **Confidential** | Yes (checked) |
| **Scopes** | `api`, `read_user`, `write_repository` |

### Step 3: Save credentials

After creating the application, GitLab displays:

* **Application ID** - Save this
* **Secret** - Save this (shown only once)

<Note>
  Unlike GitHub, GitLab credentials are entered through the BRMS UI during connection, not as environment variables. They are encrypted and stored using your secrets provider. No additional environment variables are required beyond those set in Step 1.
</Note>

## Azure DevOps configuration

Azure DevOps integration authenticates directly against Microsoft Entra ID with a client-credentials grant (service principal), or with a Personal Access Token. There is no OAuth redirect flow: no callback URL has to be registered on the Azure side, and no Azure DevOps-specific environment variables are needed.

<Warning>
  Like GitLab, Azure DevOps requires [secrets management](/developers/deployment/brms/secrets-management) to be configured. The client secret or PAT is encrypted and stored using your secrets provider.
</Warning>

### Step 1: Choose an authentication method

| Method | When to use |
| - | - |
| **Service Principal** | Recommended for Azure DevOps Services - an Entra ID app registration acting as a machine identity that does not expire with a user |
| **Access Token (PAT)** | The only option for Azure DevOps Server (on-premises), but tied to a user account and subject to expiry |

### Step 2 (Service Principal): Create an Entra ID app registration

1. In the Azure portal, go to **Microsoft Entra ID > App registrations > New registration**. No redirect URI is needed.
2. Under **Certificates & secrets**, create a **client secret** and save its value.
3. In Azure DevOps, go to **Organization settings > Users** and add the application as a member, then grant it access to the projects and repositories it should reach.
4. Collect the three values entered in the BRMS connection form:

| Field | Where to find it |
| - | - |
| **Directory (tenant) ID** | App registration overview |
| **Application (client) ID** | App registration overview |
| **Client secret** | The secret created in step 2 |

### Step 2 (Access Token): Create a PAT

In Azure DevOps, go to **User settings > Personal access tokens** and create a token with:

| Scope | Access Level |
| - | - |
| Code | Read & write |
| Build | Read & execute |

### Step 3: Connect from BRMS

All credentials are entered through the BRMS UI during connection - the **Organization URL** (`https://dev.azure.com/<organization>` for Azure DevOps Services, or your collection URL for Azure DevOps Server) plus the service principal fields or the PAT. See [Git Sync](/brms/setup/git-sync#connecting-azure-devops) for the connection flow.

## Environment variables reference

### Required for all integrations

| Variable | Description |
| - | - |
| `APP_URL` | BRMS instance URL for OAuth callbacks |
| `APP_INTEGRATIONS_SECRET` | OAuth state signing secret (min 32 chars) |

### GitHub-specific

| Variable | Description |
| - | - |
| `GITHUB_APP_ID` | GitHub App ID |
| `GITHUB_APP_PRIVATE_KEY` | Base64-encoded private key |
| `GITHUB_APP_CLIENT_ID` | OAuth Client ID |
| `GITHUB_APP_CLIENT_SECRET` | OAuth Client Secret |
| `GITHUB_APP_INSTALL_URL` | App installation URL |

### GitLab-specific

GitLab credentials are entered via the UI and stored encrypted in the database. No additional environment variables are required beyond `APP_INTEGRATIONS_SECRET`.

### Azure DevOps-specific

Azure DevOps credentials are entered via the UI and stored encrypted using your secrets provider. No additional environment variables are required beyond `APP_INTEGRATIONS_SECRET`.

## Troubleshooting

### "Integration not configured" message

The integration card shows "Not configured" when required environment variables are missing. Verify all required variables are set and restart the API server.

### GitHub: "App not installed" error

The GitHub App must be installed on the organization or account you want to connect. Users can install the app during the connection flow.

### GitLab: "Invalid redirect URI" error

The Redirect URI in your GitLab OAuth application must exactly match:

```
{APP_URL}/api/app-integrations/gitlab/callback
```

### GitLab: "URL must use HTTPS" error

GitLab requires HTTPS for OAuth applications. Ensure your GitLab URL starts with `https://`.

### Azure DevOps: "Identity is not a member of this Azure DevOps organization"

Azure DevOps reports a service principal that was never added to the organization as error `TF401444`, with a misleading suggestion to "sign in via a web browser" - which a service principal cannot do. The actual fix: add the application under **Organization settings > Users** in Azure DevOps and grant it access to the relevant projects.

### GitLab: "Secrets management required" error

GitLab integration requires secrets management to be configured. See [Secrets management](/developers/deployment/brms/secrets-management) to set up a secrets provider.


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