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 |
| Permission | Access Level |
|---|
| Contents | Read & Write |
| Pull requests | Read & Write |
- 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) |
| 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
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. 