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.

​
Fast path

Open /setup, choose GitHub, 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 /setup manual form, 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. 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 step in /setup, and confirm repository sync sees the expected repositories. 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.

​
Daily GitHub management

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
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 an environment maps the repository:
  • mention @roomote (or your deployment’s GitHub App slug) in a pull request comment to start PR review or follow-up work
  • mention the same handle in a GitHub issue comment, or in a new issue body, to start a standard task against that repository
  • link your GitHub account under Settings -> Linked Accounts so Roomote can attribute the task to you
Issue mentions use the environment mapped to the repository. Map the repository to an environment before mentioning Roomote on issues. When a task delegated from a Fast Slack or Discord conversation opens a pull request, actionable review feedback returns to that same conversation. 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.

​
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.