Connect GitLab

Connect GitLab from an existing BattleTest workspace. You need permission to connect integrations in that workspace and Maintainer or Owner access to each GitLab project you enable.

Connect your account

1. Select the intended workspace and open Settings → Integrations.
2. Choose Connect GitLab.
3. Authorize BattleTest in GitLab and return to Settings.
4. Open Repositories beside the connected account.
5. Enable the projects you want reviewed.

Enabling a project creates a project-scoped BattleTest bot service account and its merge request webhook. You do not need to create a bot account or supply a token. Only explicitly enabled projects can start reviews through this connection. Password users must verify their email before connecting.

If Settings says administrator setup is required, ask the instance administrator to configure the OAuth application. Managed users do not need to create their own application.

Posting identity

Review notes, inline discussions and commit statuses use BattleTest bot, with a separate credential for each project. Your account authorizes project selection, bot setup and webhook management. Reviews never use your account’s credential.

GitLab’s api OAuth scope gives the setup connection broad API access as the authorizing account. The bot has Developer access to its project and an encrypted token that BattleTest rotates automatically before expiry. Settings shows the project’s reviewer identity.

Project service accounts require GitLab 18.11 or later without feature flags. GitLab Free limits their number; if the instance cannot create one, enabling reviews reports the problem and does not fall back to posting as you. See GitLab service accounts.

Verify a review

Open a non-draft merge request targeting the project’s default branch, then check its BattleTest summary and commit status. Open the same review in PR Reviews in BattleTest. Push a new commit to check that another review starts for the new revision.

Draft and closed merge requests cancel an in-flight review. Becoming ready starts a review, including when no new commit was pushed. Inline findings use GitLab diff discussions. Commit statuses do not carry the full finding report; read the summary for the evidence and review coverage.

Reconnect or disable

Use Reconnect after revoking access or when authorization expires beyond recovery. Authorize the same GitLab account to preserve its project selections.

If the bot credential was revoked or expired, disable and re-enable that project after reconnecting to restore its bot access.

Turn off a project in Repositories to stop reviews, or choose Disconnect to disable all projects on that connection. BattleTest removes its webhooks and revokes its bot tokens while preserving review history. If GitLab is unavailable, review access is revoked locally and any remaining provider cleanup is reported. Restore provider access and retry disconnect to finish cleanup.