Git integrations

Git Sync and Git-based webhooks require integration with a Git provider (GitHub, GitLab or Azure DevOps). 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 and Azure DevOps)

Required environment variables

All provider 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.

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.

Like GitLab, Azure DevOps requires secrets management to be configured. The client secret or PAT is encrypted and stored using your secrets provider.

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

In the Azure portal, go to Microsoft Entra ID > App registrations > New registration. No redirect URI is needed.
Under Certificates & secrets, create a client secret and save its value.
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.
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 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 to set up a secrets provider.

Overview

AI & Tools

Deployment

CI/CD Integrations

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

Azure DevOps configuration

Step 1: Choose an authentication method

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

Step 2 (Access Token): Create a PAT

Step 3: Connect from BRMS

Environment variables reference

Required for all integrations

GitHub-specific

GitLab-specific

Azure DevOps-specific

Troubleshooting

”Integration not configured” message

GitHub: “App not installed” error

GitLab: “Invalid redirect URI” error

GitLab: “URL must use HTTPS” error

Azure DevOps: “Identity is not a member of this Azure DevOps organization”

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

​Azure DevOps configuration

​Step 1: Choose an authentication method

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

​Step 2 (Access Token): Create a PAT

​Step 3: Connect from BRMS

​Environment variables reference

​Required for all integrations

​GitHub-specific

​GitLab-specific

​Azure DevOps-specific

​Troubleshooting

​”Integration not configured” message

​GitHub: “App not installed” error

​GitLab: “Invalid redirect URI” error

​GitLab: “URL must use HTTPS” error

​Azure DevOps: “Identity is not a member of this Azure DevOps organization”

​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

Azure DevOps configuration

Step 1: Choose an authentication method

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

Step 2 (Access Token): Create a PAT

Step 3: Connect from BRMS

Environment variables reference

Required for all integrations

GitHub-specific

GitLab-specific

Azure DevOps-specific

Troubleshooting

”Integration not configured” message

GitHub: “App not installed” error

GitLab: “Invalid redirect URI” error

GitLab: “URL must use HTTPS” error

Azure DevOps: “Identity is not a member of this Azure DevOps organization”

GitLab: “Secrets management required” error