Git integrations

Git Sync requires integration with a Git provider (GitHub or GitLab). This guide covers the server-side configuration for self-hosted BRMS deployments.

For instructions on connecting and using Git Sync from the BRMS interface, see Git Sync.

Prerequisites

Before configuring Git integrations, ensure you have:

A running BRMS instance with a publicly accessible URL (required for OAuth callbacks)
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.

# 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

Go to GitHub > Settings > Developer settings > GitHub Apps
Click New GitHub App
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

Check Request user authorization (OAuth) during installation
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:

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

base64 -i your-app-name.private-key.pem

Step 5: Set GitHub environment variables

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

GitLab integration requires 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.

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)

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.

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 to set up a secrets provider.

Overview

AI & Tools

Deployment

Platform Guides

SDKs

Big Data

JDM

Prerequisites

Required environment variables

GitHub configuration

Step 1: Create a GitHub App

Step 2: Configure permissions

Step 3: Configure installation settings

Step 4: Generate credentials

Step 5: Set GitHub environment variables

GitLab configuration

Step 1: Create an OAuth application

Step 2: Configure the application

Step 3: Save credentials

Environment variables reference

Required for all integrations

GitHub-specific

GitLab-specific

Troubleshooting

”Integration not configured” message

GitHub: “App not installed” error

GitLab: “Invalid redirect URI” error

GitLab: “URL must use HTTPS” error

GitLab: “Secrets management required” error

​Prerequisites

​Required environment variables

​GitHub configuration

​Step 1: Create a GitHub App

​Step 2: Configure permissions

​Step 3: Configure installation settings

​Step 4: Generate credentials

​Step 5: Set GitHub environment variables

​GitLab configuration

​Step 1: Create an OAuth application

​Step 2: Configure the application

​Step 3: Save credentials

​Environment variables reference

​Required for all integrations

​GitHub-specific

​GitLab-specific

​Troubleshooting

​”Integration not configured” message

​GitHub: “App not installed” error

​GitLab: “Invalid redirect URI” error

​GitLab: “URL must use HTTPS” error

​GitLab: “Secrets management required” error

Prerequisites

Required environment variables

GitHub configuration

Step 1: Create a GitHub App

Step 2: Configure permissions

Step 3: Configure installation settings

Step 4: Generate credentials

Step 5: Set GitHub environment variables

GitLab configuration

Step 1: Create an OAuth application

Step 2: Configure the application

Step 3: Save credentials

Environment variables reference

Required for all integrations

GitHub-specific

GitLab-specific

Troubleshooting

”Integration not configured” message

GitHub: “App not installed” error

GitLab: “Invalid redirect URI” error

GitLab: “URL must use HTTPS” error

GitLab: “Secrets management required” error