Prerequisites
Before you begin, make sure you have:
- An active Userorbit account with admin or owner permissions.
- A GitHub account with access to the repositories you want to connect.
Step 1: Open the Integrations page
Log in to Userorbit and navigate to Settings > Integrations from the left sidebar. You will see a list of available integrations. Locate the GitHub card and click Connect.
Step 2: Authorize Userorbit on GitHub
Clicking Connect opens a GitHub authorization window. Review the permissions Userorbit is requesting:
- Read access to repository metadata so Userorbit can list your repos and issues.
- Write access to issues so Userorbit can create new issues and update their status on your behalf.
Click Authorize to grant access. You will be redirected back to Userorbit automatically. If your GitHub organization requires admin approval for third-party apps, an organization owner will need to approve the request from the GitHub settings page before the integration becomes active.
Step 3: Select repositories
After authorization, Userorbit displays a list of repositories you have access to. Select the repositories you want to link with Userorbit. You can connect multiple repositories — for example, one for your main product and another for your mobile app.
Click Save to confirm your selection. You can return to this screen at any time to add or remove repositories.
Step 4: Map issues to feedback items
With repositories connected, you can now link GitHub issues to Userorbit feedback items. There are two ways to do this:
From a feedback item
- Open any feedback item in Userorbit.
- In the sidebar, find the GitHub section.
- Click Create issue to generate a new GitHub issue pre-filled with the feedback title and description. Select the target repository and add labels if needed.
- Alternatively, click Link existing issue and paste the URL of an issue that already exists in GitHub.
From GitHub
When someone references a Userorbit feedback URL in a GitHub issue or pull request, Userorbit detects it and displays the link in the feedback item's sidebar automatically.
Step 5: Configure status syncing
By default, Userorbit syncs issue status changes in both directions:
- When a linked GitHub issue is closed, the corresponding feedback item's status updates to Done in Userorbit.
- When you mark a feedback item as Done in Userorbit, the linked GitHub issue is closed.
You can customize this behavior from the GitHub integration settings page. Options include disabling two-way sync or mapping specific GitHub labels to Userorbit statuses.
Troubleshooting
- Repositories not appearing — Make sure you have at least read access to the repository on GitHub. Organization-owned repos may require the Userorbit app to be approved by an org admin.
- Status not syncing — Verify that webhooks are active in the repository's GitHub settings. Userorbit registers a webhook automatically during setup, but it can be accidentally removed.
- Authorization expired — If the integration stops working, disconnect and reconnect it from Settings > Integrations to refresh the OAuth token.