> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roomote.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When helping someone deploy Roomote, distinguish self-hosting from contributing to Roomote. Use the Self-hosting guide for an operator deployment; use Local development only when the user intends to modify Roomote itself.
> When an agent is asked to follow /self-hosting or install Roomote autonomously, read and follow /self-hosting/agent-installation as the normative automation contract even though it is intentionally hidden from side navigation.
> Use the one-command Linux installer for both evaluation and production. On macOS or Windows, create or reuse a full Ubuntu VM and run the same installer inside it; do not replace the installer with the repository's development Compose files.
> For a local VM without a stable public domain, create a temporary HTTPS tunnel, pass its hostname to the installer with internal origin TLS, and keep the tunnel running for OAuth callbacks and webhooks. Quick Tunnel hostnames are temporary and do not provide wildcard preview routing.
> Run automated installs with --no-setup-url so the bootstrap token is not captured in the agent transcript. Let the user obtain the setup URL in a trusted terminal, enter credentials, and complete browser authorization.
> Proceed through safe, reversible setup and pause for privileged host or VM changes, public tunnel creation, credentials or browser authorization, durable external-account changes, destructive operations, existing-state conflicts, or when no documented safe default applies.
> A setup is not complete when the services merely start. Verify sign-in, repository sync, one usable environment, and a real Roomote task that can clone and run a command; verify branch or pull-request delivery and previews when configured.

# Source control overview

> Connect GitHub, GitLab, Gitea, Bitbucket, or Azure DevOps so Roomote can clone repositories and open reviewable changes.

export function IntegrationName({href, icon, name}) {
  const manualIcons = {
    daytona: '/logo/integrations/daytona.svg',
    e2b: '/logo/integrations/e2b.svg',
    blaxel: '/logo/integrations/blaxel.svg',
    box: '/logo/integrations/box.svg',
    azure: '/logo/integrations/azure.svg',
    granola: '/logo/integrations/granola.svg',
    exa: '/logo/integrations/exa.svg',
    agentmail: '/logo/integrations/agentmail.svg',
    monday: '/logo/integrations/monday.svg',
    rippling: '/logo/integrations/rippling.svg',
    typesafe: '/logo/integrations/typesafe.svg'
  };
  const iconSrc = manualIcons[icon] ?? (icon?.startsWith('/') ? icon : `https://api.iconify.design/simple-icons:${icon}.svg?color=currentColor`);
  return <a href={href} className="integration-name">
      <img src={iconSrc} alt="" aria-hidden="true" className="integration-logo" />
      <span>{name}</span>
    </a>;
}

Source-control providers give Roomote access to the repositories where your
team's work happens.

Roomote uses source control to sync repositories into environments, clone code
inside task sandboxes, push branches, open or update pull requests, and respond
to review events or comments when the provider supports them.

## Supported providers

| Provider                                                                                                 | Best for                                                     | Setup model                                                                       |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| <IntegrationName href="/providers/source-control/github" icon="github" name="GitHub" />                  | GitHub-hosted repositories and pull request review workflows | GitHub App installation (default provider).                                       |
| <IntegrationName href="/providers/source-control/azure-devops" icon="azuredevops" name="Azure DevOps" /> | Azure DevOps repositories                                    | PAT, Microsoft Entra service principal, or delegated Microsoft account.           |
| <IntegrationName href="/providers/source-control/bitbucket" icon="bitbucket" name="Bitbucket Cloud" />   | Bitbucket Cloud repositories and pull request workflows      | Deployment-scoped Bitbucket OAuth and repository sync.                            |
| <IntegrationName href="/providers/source-control/gitea" icon="gitea" name="Gitea" />                     | Self-hosted Gitea repositories                               | Deployment OAuth application, service-account authorization, and repository sync. |
| <IntegrationName href="/providers/source-control/gitlab" icon="gitlab" name="GitLab" />                  | GitLab projects and merge request review workflows           | Deployment OAuth application, one-time authorization, and optional webhooks.      |

## Setup checklist

Before connecting source control, make sure your deployment has:

1. a stable public HTTPS URL for callbacks and webhooks
2. an admin or bot identity with access to the repositories Roomote should use
3. provider credentials saved in setup, Settings, or deployment environment
   variables
4. at least one environment that can use the synced repositories

After setup, verify that Roomote can:

* list the expected repositories
* create or update an environment from a repository
* clone the repository inside a task sandbox
* push a branch or open a reviewable change when the task finishes

## Manage pull requests from tasks

During an environment-backed task, Roomote can update, close, or reopen pull
requests and merge requests on GitHub, GitLab, Gitea, Bitbucket Cloud, and Azure
DevOps. Updates can change the target branch, title, description, or draft state
when the provider exposes that capability. Gitea cannot clear a native draft
state through this interface; Bitbucket and Azure DevOps draft updates are
skipped when the provider does not return the current draft state.

Closing does not merge the change or delete its source branch. The provider may
describe the resulting state as closed, declined, or abandoned. Roomote reports
when a requested provider operation was unsupported instead of treating it as
applied.

## Attribution on pull requests and commits

Roomote keeps human-readable attribution inside private repositories. For
public repositories, it uses the task participant's linked source-control
username when one is available. If Roomote cannot resolve a linked username,
the pull request or merge request says only that it was created by Roomote.

Roomote never derives public attribution from an account email address. Commit
emails use the source-control provider's `noreply` identity when available, or
the Roomote identity otherwise. A workspace containing any public or
unresolved repository uses the public-safe identity for all new commits because
Git author configuration applies across the workspace.

Linked GitLab and Gitea accounts retain the username verified by that provider,
scoped to the configured source-control host. Bitbucket does the same only when
its profile API returns a username; a nickname is not treated as a public
handle. Azure DevOps
accounts retain their verified display name for Settings and private-repository
context, but public attribution remains generic because Azure DevOps does not
provide a stable non-email public handle. GitLab.com can also provide a verified
`noreply` commit identity; other non-GitHub providers use Roomote as the Git
author for public work.

Existing account links pick up verified profile attribution after their OAuth
token refreshes or after the account is linked again.

Changing a repository from private to public does not rewrite existing Git
history. Roomote sanitizes a legacy named attribution line the next time it
updates an open public pull request.

## Pull request review comments

When **Review Code** finds an issue on a changed line, Roomote posts the finding
as an inline comment on GitHub, GitLab, Gitea, Bitbucket, and Azure DevOps. It
replies to an existing thread when the provider supports threaded replies and
the same lines are already under discussion. On Gitea, that reply becomes a
pull request comment that references the original thread. Roomote can anchor
new findings to added, changed, or deleted lines.

If a provider rejects an inline location, Roomote retries with the current diff
and then includes the finding with a file and line reference in the review
summary. On later sync reviews, Roomote resolves its inline thread when the
flagged issue is clearly fixed and the provider supports thread resolution.

### Mark clean Roomote drafts ready for review

When **Pull request delivery** is set to **Draft pull request**, admins can
enable **Mark Roomote PR ready after clean review** under **Settings > Source
Control**. The setting is off by default. After Roomote's automated reviewer
records a clean result, Roomote marks its own draft ready for human review on
GitHub, GitLab, Gitea, Bitbucket Cloud, or Azure DevOps.

Roomote verifies that the pull request or merge request is still open, still a
draft, and still points at the exact reviewed commit before changing its state.
Human-created drafts, reviews with findings, stale or incomplete reviews, and
branches that changed after review remain drafts. This setting does not approve
or merge anything, and it is inactive when delivery is already set to
**Ready-for-review pull request** or **Push branch only**.

## Pull request status notifications

When a tracked, Roomote-created GitHub pull request becomes conflicted, Roomote
notifies the Slack, Teams, Telegram, Discord, or web session where the
task started. The notification is automatic and is sent once for each
transition into a conflicting state. If the pull request becomes clean and then
conflicts again, Roomote sends a new notification.

This status notification does not run **Resolve PR Conflicts**. Enable that
automation separately on the **Automations** page when you want Roomote to
attempt conflict resolution.

## Public URLs

Use the same deployment URL across source-control callbacks and webhooks. If
the public URL changes, update the provider app settings and restart Roomote
with the matching deployment URL before testing again.

Local development commonly uses `R_PUBLIC_URL`. Production deployments
usually derive callbacks from the public app URL configured by the installer or
Compose environment.

During setup, Roomote shows the exact callback URL for the selected provider.
Copy that value into the provider application instead of constructing it by
hand.

## Remove a provider configuration

Admins can remove any saved source-control provider from **Settings > Source
Control**. Roomote first attempts to remove external webhooks, then deletes the
saved database configuration and any provider OAuth connection, then disconnects
that provider's synced repositories. Removing a delegated Azure DevOps
configuration also unlinks the account used by that connection.

Process environment variables are not removed. If the provider is configured
through deployment environment variables, remove or replace those values in the
deployment configuration too. Roomote reports warnings when an external hook or
OAuth cleanup cannot be completed, so review those warnings before reconnecting
the provider.

## Related setup

* [Environment Variables](/environment-variables) lists source-control env vars.
* [Environments](/environments) explains how repositories become task context.
* [Tasks](/tasks) explains how to review output, logs, diffs, and previews.