> ## 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 and GitLab integrations for Git Sync in self-hosted deployments.

Git Sync requires integration with a Git provider (GitHub or GitLab). 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)

## Required environment variables

Both GitHub and GitLab 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>

## 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`.

## 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://`.

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