Skip to main content
GitLab does not have a GitHub-style App installation flow. Configure a GitLab OAuth application for Roomote’s deployment, then authorize it once so Roomote can sync repositories, run tasks, add merge-request notes, and manage webhooks. Use <public-url> below for your stable public Roomote URL (R_PUBLIC_URL when set, otherwise R_APP_URL). The GitLab OAuth application redirect URI must match the callback Roomote builds for authorize and token exchange.

​
Create a GitLab OAuth application

Create the application on the GitLab account, group, or instance that should own Roomote’s access. Use these settings:
  • Confidential: enabled
  • Redirect URI: <public-url>/api/source-control/gitlab/oauth/callback
  • Scopes: api
Save the application credentials in setup, deployment env vars, or local .env.local:
For self-managed GitLab, also set GITLAB_BASE_URL.

​
Sync repositories

After the application credentials are configured, open Settings, go to the Environments page, authorize GitLab, and use the Source Control section’s sync button. Roomote lists the projects visible to the authorized GitLab account and stores them as GitLab repository rows. GitLab-backed tasks clone from the synced repository row, so sync must run before launching a GitLab-backed task.

​
Configure webhooks

Create a GitLab project or group webhook for merge request, issue, comment, and pipeline events. Repository sync configures these project webhook events automatically when the authorized identity has permission to manage hooks. Webhook URL:
Enable:
  • Merge request events
  • Issues events
  • Comments
  • Pipeline events
Preferred verification uses GitLab signed webhook headers. Set a GitLab signing token on the webhook and save the same value in Roomote:
Legacy secret-token verification is also supported:
Once the application is configured, users can link their personal GitLab accounts in Roomote’s Personal settings and talk to Roomote by mentioning @roomote in merge request or issue notes. Each merge request or issue is a Roomote session: Roomote reads the discussion, answers as a note when no workspace is needed, and otherwise starts a task on the merge request’s source branch (or the issue’s repository) and reports back in the same discussion. Mention it again to redirect it, ask a follow-up, or steer a running task. Ask for a review in the mention (for example @roomote review this) and Roomote runs the Review Code automation’s structured review on the current head, posts the findings on the merge request, and reports back in the same discussion.

​
Enable review automation

GitLab merge-request reviews use the same Review Code automation targeting model as GitHub. After syncing repositories, enable Review Code automation. A repository doesn’t need an environment: reviews run in the environment that includes the repository when one exists, and otherwise on a plain checkout of the repository. Open or reopened merge request events enqueue initial review tasks. Update events enqueue sync reviews when GitLab includes oldrev, which indicates a code-related update.

​
Enable CI failure triage

Associate the GitLab repository with an environment, configure the Manager Channel destination, and enable CI Failure Triage under Automations. Failed default-branch Pipeline Hooks start an environment-backed Roomote task. Roomote reads a bounded tail of the failed job logs with the deployment GitLab credential, reproduces the relevant commands locally, and opens a merge request when it can fix the failure.

​
Verify setup

  1. sync GitLab repositories from Settings
  2. create or update an environment from a synced repository
  3. start a small task and confirm Roomote can clone the repository
  4. open or update a merge request and confirm configured review automation runs
  5. trigger a failing default-branch pipeline and confirm CI Failure Triage starts

​
Native GitLab API tools for sessions

Roomote can read code and handle supported merge request requests directly through GitLab’s API without cloning a repository. These tools are built into Roomote: no extra MCP server, package installation, or server URL is required. Roomote reuses its active deployment OAuth connection with the existing api grant and refreshes the access token when needed. No second OAuth application, user authorization flow, or static GitLab credential is needed. GitLab’s official MCP server uses mcp-scoped authorization; it is not a drop-in replacement for Roomote’s unchanged api grant. A community MCP server is not required for these operations. Hosting one would add responsibility for deployment, version pinning and upgrades, network and TLS configuration, authentication, credential protection, tool permissions, monitoring, and incident response. It would also introduce another service trusted with GitLab credentials and repository data. The native tools avoid that additional operational burden while using the connection configured above.

​
Available operations and limits

All tools require project_id: a positive integer project ID (number or decimal string without leading zeros), or a group/project path, including subgroups. MR tools also require merge_request_iid as a positive decimal string without leading zeros, within JavaScript’s safe integer range. Unknown inputs are rejected. Inputs listed as optional below may be omitted. Paths (file_path, path, and sha) must be nonempty and cannot contain backslashes, control characters, empty slash-separated segments, or . / .. segments. Project paths use letters, digits, underscores, dots, and hyphens in each segment. Decimal string project IDs must fit JavaScript’s safe integer range. Tree page tokens are nonempty and contain only letters, digits, underscores, +, /, =, or -. Paginated tools accept integer per_page from 1-100, default 20. Tools other than trees accept integer page of at least 1, default 1, with no additional page-number cap. They return items and next_page; null means no next page. The complete incoming request is limited to 64 KiB. GitLab responses and the complete tool result are each capped at 1 MiB. Operations have a 20-second abort deadline; OAuth refresh requests have a 10-second timeout. Request smaller pages or file windows if a result exceeds the response limit. There are no separate native character caps for titles, descriptions, or note bodies; the request-size limit and GitLab’s own validation still apply. Every operation requires an active Roomote member or admin, an active connected repository on the configured host, and valid deployment OAuth access. MR writes also verify the target MR and, for replies, its discussion before sending the write. These native tools do not expose file or branch writes, MR creation, approvals, thread resolution, note editing/deletion, issue tools, CI tools, or arbitrary GraphQL. Roomote uses available APIs first for this supported scope. Local checkout inspection, edits, commands, and validation still need a task. Task authorization and structured code reviews are unchanged.

​
Verify safely

  1. From a signed-in member or admin session, ask Roomote to discover available GitLab tools and read a small known file in an active synced repository at a resolved commit SHA. Confirm it uses the API without launching a clone task.
  2. If tools are missing, check that you are an active Roomote member or admin, the deployment’s GitLab OAuth connection is active with the api scope, and repository sync includes an active repository on the configured GitLab host. Reauthorize if required. Curated integrations must not be disabled on the Roomote deployment. No external MCP server needs to be installed or repaired.
  3. Test writes only with explicit authorization on a designated disposable MR. Specify the exact note, reply, or reversible title/state change, inspect the result in GitLab, and restore any changed fields. Never mutate arbitrary MRs as a connectivity check. For a merge, Roomote reads the MR immediately before the mutation, binds it to expected_head_sha, and reads it again before reporting success or retrying an ambiguous result. Successful discovery or reads do not prove live authorized writes; verify each required operation before relying on it.