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. 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:
<public-url>/github/callback
  1. Check Redirect on update.
  2. Set Callback URL to:
<public-url>/github/callback
  1. Enable Expire user authorization tokens.
  2. Set Webhook URL to:
<public-url>/api/webhooks/github
  1. Generate a webhook secret and save the same value in Roomote:
openssl rand -hex 32

​
Permissions and events

Grant these repository permissions:
  • Contents: Read and write
  • Issues: Read and write
  • Metadata: Read-only
  • Pull requests: Read and write
  • Workflows: Read and write
Subscribe to these events:
  • Installation
  • Issue comment
  • Pull request
  • Pull request review comment
  • Push
  • Workflow run

​
Save credentials

Copy these values into the /setup manual form, deployment env vars, or your local .env.local: 
GITHUB_APP_ID=<app-id>
GITHUB_CLIENT_ID=<client-id>
GITHUB_CLIENT_SECRET=<client-secret>
GITHUB_WEBHOOK_SECRET=<webhook-secret>
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
NEXT_PUBLIC_GITHUB_APP_SLUG is optional when your GitHub App slug is not roomote. 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: 
awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' ~/Downloads/<your-key>.private-key.pem
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.

​
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

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