Skip to main content
Use GitHub when your Roomote environments should come from GitHub repositories. Roomote uses a GitHub App installation token to sync repositories, clone code, push branches, and work with pull requests. Use <public-url> below for your stable public Roomote URL.

​
Session path

Open /setup and complete the short account and inference bootstrap. In the setup conversation, choose GitHub in the source-control card, open its configuration dialog, and click Create GitHub App. Roomote sends GitHub a manifest with the callback, webhook, permissions, and events preconfigured. After GitHub redirects back, Roomote saves the generated app ID, app slug, OAuth client credentials, webhook secret, and private key, then sends you to install the app on repositories. You pick the account or organization to install on during that install step. By default the app is created on your personal GitHub account and marked as installable on any account, so you can install it on any organization you belong to. If your organization should own the app instead, click Show advanced config and enter the organization name before clicking Create GitHub App. Use the manual steps only when you already have a GitHub App or want to manage these values in deployment environment variables yourself.

​
Manual GitHub App setup

  1. Go to GitHub App settings. For an organization-owned app, use the organization’s Developer settings > GitHub Apps > New GitHub App page.
  2. Set GitHub App name to a unique name.
  3. Keep Identifying and authorizing users enabled.
  4. Set Homepage URL to <public-url>.
  5. Set Setup URL to:
  1. Check Redirect on update.
  2. Set Callback URL to:
  1. Enable Expire user authorization tokens.
  2. Set Webhook URL to:
  1. Generate a webhook secret and save the same value in Roomote:
  1. Under Where can this GitHub App be installed?, choose Any account if you want to install the app somewhere other than the account that owns it. Only on this account also works when the owning account is where you will install it.

​
Permissions and events

Grant these repository permissions:
  • Actions: Read and write
  • Checks: Read and write
  • Contents: Read and write
  • Commit statuses: Read-only
  • Deployments: Read-only
  • Dependabot alerts: Read-only
  • Code scanning alerts: Read-only
  • Issues: Read and write
  • Merge queues: Read-only
  • Metadata: Read-only
  • Organization projects: Read and write
  • Pull requests: Read and write
  • Workflows: Read and write
Subscribe to these events:
  • Check run
  • Check suite
  • Commit comment
  • Create
  • Delete
  • Dependabot alert
  • Deploy key
  • Deployment
  • Deployment protection rule
  • Deployment review
  • Deployment status
  • Fork
  • Gollum
  • Installation target
  • Issue comment
  • Issue dependencies
  • Issues
  • Label
  • Merge group (merge queue entry)
  • Meta
  • Milestone
  • Public
  • Pull request
  • Pull request review
  • Pull request review comment
  • Pull request review thread
  • Push
  • Release
  • Repository
  • Repository dispatch
  • Security advisory
  • Star
  • Status
  • Sub issues
  • Watch
  • Workflow dispatch
  • Workflow job
  • Workflow run
GitHub Apps also receive installation and installation_repositories events automatically; you do not need to subscribe to them in the app form. Roomote uses the Repository and installation_repositories events to pick up newly created or newly granted repositories without a manual refresh. If your app was created before the Repository event was part of the manifest, confirm it is enabled under the app’s Permissions & events page — GitHub has no API to update an app’s event subscriptions.

​
Save credentials

Copy these values into the source-control card’s configuration dialog, deployment env vars, or your local .env.local:
R_GITHUB_APP_SLUG is required when your GitHub App slug is not roomote; Roomote uses it for GitHub mentions and bot-authored PR detection. If trusted review or notification activity can also come from other Roomote GitHub Apps, list their exact slugs in R_GITHUB_ADDITIONAL_APP_SLUGS:
Roomote treats only the primary slug and this comma-separated allowlist as managed bot identities. Do not add unrelated GitHub Apps. Roomote can use the GitHub App’s Actions access to inspect workflow runs, jobs, and logs when it explains a CI failure. That diagnostic path is read-only even though the app keeps broader Actions and Workflows permissions for normal task and automation workflows. Generate a private key from the app’s Private keys section. GitHub downloads a .pem file. Convert it to an escaped single-line value before saving it in an env var:
Install the GitHub App on the repositories Roomote should use. Then sign in, complete the GitHub card in the setup conversation, and confirm repository sync sees the expected repositories. If a repository stamped onto an existing task is later deleted or removed from the GitHub App, Roomote can resume the task using the stamped repositories that remain available. Resumption still fails when none of the task’s stamped repositories remain accessible; reconnect or restore repository access before continuing that task. To replace a saved GitHub App, open Settings > Source Control and select Remove. Roomote removes the saved deployment credentials and disconnects existing GitHub repositories so you can configure another app. Process environment variables are not changed. If you add Organization projects permission to an existing app, an organization owner must approve the updated permission before Roomote can manage project items.

​
Public GitHub reads

An eligible deployment GitHub App installation with an active connected repository is required to mint the scoped installation token used by the GitHub tools, including public reads. With that connection, active Roomote members can inspect any public github.com repository in a session without connecting the public target or linking a personal GitHub account. The same reads are available in coding tasks, including automated tasks without a human driver. No clone or personal access token is needed. Use the existing GitHub tools for files and directories, code search, issues, and pull requests. Tool discovery supplies their native descriptions and argument schemas. Searches use GitHub’s own query syntax; adding a repo:owner/name or org: qualifier, for example Hello repo:octocat/Hello-World, keeps results focused. GitHub’s tool availability, permissions, rate limits, pagination, and search-index limits apply; partial or empty search results are not proof of absence. Native reads of unconnected repositories are limited to 2 MiB of response bytes and a 15-second upstream deadline, including JSON or SSE body reads. Oversized, timed-out, or failed reads are not retried through another path. These additional limits do not apply to connected repository calls. Unconnected reads use the token of the deployment’s first installation, which covers the repositories connected on that installation. GitHub denies private repositories outside that token’s scope. Private reads and all writes still require an eligible connection to the target repository. Connected access keeps its existing authorization; Roomote does not retry lookup or authorization failures through another credential. The coding-task GitHub MCP remains read-only; writes use the existing authorized coding-task source-control workflow. Other source-control providers are unchanged.

​
Multiple installations and searches

GitHub tool discovery supports multiple installations of the configured GitHub App. Connected repository reads and supported writes use the installation connected to the requested active repository, with one token covering every repository connected on that installation. Suspended installations, inactive or disconnected repositories, and installations of a different app are not eligible. Personal GitHub account linkage is not required for these deployment-connected tools; coding-run tokens remain read-only on this MCP path. Identify the repository with owner and repo for repository tools. Code, pull request, and repository searches accept GitHub’s query syntax as written, including searches that span several repositories. Each call runs under one installation’s credential, covering every repository connected on that installation plus public repositories: the installation that owns the repository named by owner/repo or a repo:owner/name qualifier, otherwise the deployment’s first installation. With more than one installation, scope a search to the organization or repository you mean so it runs under the right one.

​
Daily GitHub management

Roomote can use GitHub’s native tools directly, without starting a coding task: pull request and issue edits, comments, replies and reactions, reviews, labels, branches, and small file changes. Their discovered descriptions and schemas define the supported arguments. These actions use the deployment GitHub App, require an active Roomote member, and run under a token that reaches only the repositories connected on that installation, the same boundary a coding task has. What the token may do there is set by the App’s permissions on GitHub. No personal GitHub OAuth connection is required. Ask for the specific change and identify the repository and target issue, pull request, or comment. Every call appears in the session transcript with its inputs and result. For example, ask Roomote to:
  • mark PR #42 in example/repo ready for review
  • request a review from octocat on that PR
  • merge PR #42 after its required checks and reviews pass
  • enable auto-merge on PR #42 so it merges once its checks and reviews pass
  • add a thumbs-up reaction to an existing comment, providing its GitHub URL
Retargeting a pull request’s base to an existing branch does not write a branch or change files. A merge or auto-merge request requires an explicit request from the current human message. Roomote reads the pull request immediately before the mutation and binds the request to the current head SHA; for auto-merge, GitHub enforces that binding atomically and rejects the call when the head has moved. Branch protections, required checks, and merge permissions stay with GitHub, and Roomote reads the pull request again before reporting success or retrying an ambiguous result. Auto-merge is only enabled when GitHub confirms it, and only where the repository allows auto-merge and the requested merge method. Work that needs a checkout, a build, or tests to get right still belongs in a coding task, which also remains read-only on this GitHub tool path and writes through its own checkout instead. GitLab and Bitbucket Cloud have their own supported session operations and limits. Native updates that combine several actions are not guaranteed to be atomic. After an error, Roomote inspects the resulting state before retrying so an action that already succeeded is not blindly repeated. Roomote tasks can manage routine repository work through the GitHub App installation. Requests default to the repository mapped to the task:
  • list, create, edit, delete, and apply labels to issues or pull requests
  • create, update, delete, and report progress for milestones; assign issues to milestones
  • list accessible GitHub Projects V2, inspect an issue or pull request’s Status, and update an existing project item’s single-select Status field
An environment-backed task can also push branches and create or update pull requests in another active GitHub repository connected to the same GitHub App installation, even when that repository is not part of the environment workspace. This write access does not automatically add the repository to the prepared workspace. Roomote rejects inactive repositories, repositories connected through another provider, and repositories that belong to a different GitHub App installation. Read-only requests, creations, and additive label actions run directly. Before editing, replacing, assigning, clearing, moving, or deleting an item, Roomote shows the proposed change and asks for confirmation. Deletions name the resource and URL in that confirmation. After a write, Roomote reads the result back and shares its GitHub URL. Projects V2 operations require the Organization projects permission above. If a project or Status field is ambiguous, Roomote asks you to choose one. An issue or pull request that is not already on a project is reported as such; Roomote does not add it automatically. Native GitHub saved views are not currently supported. Roomote can share an issue-search URL, but it does not represent that URL as a saved GitHub view.

​
Start work from issues and pull requests

Once the app is installed and the repository is synced:
  • mention @roomote (or your deployment’s GitHub App slug) in a pull request comment, review comment, or review to talk to Roomote about that pull request
  • mention the same handle in a GitHub issue comment, or in a new issue body, to talk to Roomote about that issue
  • link your GitHub account under Settings -> Linked Accounts so Roomote can run the conversation as you
Each pull request or issue is a Roomote session. Roomote reads the discussion, answers as a comment when no workspace is needed, and otherwise starts a task on the pull request’s 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. Replies to a review comment stay in that review thread. 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 pull request, and reports back in the same discussion. Review Code does not require the repository to be mapped to an environment. When an environment includes the repository, the review runs there; otherwise, Roomote uses a plain checkout of the active synced repository. Other coding work still requires a suitable environment when it needs environment-specific setup. To request a fresh review through GitHub, use Re-run on the Roomote code review check for the pull request’s current head. Roomote ignores rerun events for stale commits and checks that were not created by the configured Roomote GitHub App. Roomote only responds to comments that @mention it, including replies inside a review thread it opened, so people can discuss a finding among themselves without summoning it. On a pull request that a Roomote task opened, replies in its review threads are collected as review feedback for the owning session, described below. A pull request that a Roomote task opened already belongs to the session that started the work, for example the Slack thread where the task was requested. Mentions on that pull request join that session instead of opening a second one: Roomote answers on the pull request and in the session’s home surface, and any work it delegates runs on the pull request’s branch from the same session. When a Roomote task opens a pull request, actionable review feedback returns to the owning session and appears in both session and standard web task transcripts. Use Resolve these issues to address the current feedback, Auto-resolve on this PR to handle later actionable feedback automatically, or Dismiss to take no action. Failed GitHub checks also return to every Roomote task linked to the pull request and to the conversation that started the work. Roomote consolidates a burst of failures into one actionable notification with the check names and links. It suppresses failures from an outdated head commit and stays silent for successful or non-failing conclusions. Keep the Checks permission and Check run event enabled so these notifications reach Roomote, including for pull requests opened from forks.

​
Verify setup

  1. connect GitHub in setup or Settings
  2. install the app on at least one repository
  3. create or update an environment from that repository
  4. start a small task and confirm Roomote can clone the repository
  5. finish the task and confirm Roomote can push a branch or open a pull request
  6. optionally mention Roomote on a test issue and confirm a reply with a task link

​
URL changes

Keep the public URL stable. If it changes, update both the GitHub App callback URL and webhook URL, then restart Roomote with the matching URL.