GitHub integration

Connecting GitHub links one of your apps to a single repository. From then on, every report submitted from that app automatically opens a GitHub issue with the description, screenshots, and the reporter's classification.

You can connect more than one tracker to the same app; each report fans out to every connected integration independently.

• You've created an app in the BugScreen console.
• You can sign in to a GitHub account that can create issues in the repository you want reports filed into. We recommend a dedicated account owned by your team rather than a personal one — see below.

We recommend authorizing BugScreen with a dedicated GitHub account owned by your team, rather than with a personal one. It takes a few minutes and avoids two problems.

Issues are attributed to whoever authorized. GitHub records that account as the author of every issue BugScreen opens — so it's your name on each one.

The connection outlives staff changes. The token BugScreen holds belongs to that account, so removing it from the repository — when someone leaves — stops issue creation until you reconnect.

Setting one up

1. Create a GitHub account on an address your team controls — for example [email protected]. GitHub's terms permit a machine account for automation like this.
2. Set its display name to BugScreen, so filed issues are clearly attributed.
3. Add it to the repository — or organization — you plan to connect, with write access so it can create issues.
4. Sign out of GitHub and back in as that account — or use a private window — then follow the connect steps below. The authorization screen reuses whichever GitHub session your browser already has, so it won't offer you an account picker.

On paid organizations this uses one seat.

1. Open your app in the console and go to the Integrations section.
2. Click Connect GitHub. You'll be redirected to GitHub to authorize BugScreen.
3. Approve the authorization on GitHub. You'll be returned to the console.
4. Enter the repository owner and name that issues should be filed into, then confirm.

Each report opens a GitHub issue containing:

• A title derived from the report.
• A Markdown body with the description and any device or page metadata.
• Screenshots embedded inline under a ## Screenshot heading.
• The reporter's classification rendered in the body.

Labels

BugScreen applies a consistent set of labels so you can filter and automate:

• bugscreen and bug on every issue.
• type:bug, type:ui, or type:crash from the reporter's type.
• severity:low, severity:medium, or severity:high from the reporter's severity.

After connecting, use Test on the integration to confirm everything works end to end. The test files a real sample issue and shows you whether it succeeded.

To file issues into a different repository, pick a different owner/repo from the integration — no need to reconnect. To stop filing issues entirely, disconnect the integration from the app's Integrations section.

If a test or real report fails to create an issue, check the following:

• The authorized account lost access — or was removed. A common cause is that the person who connected GitHub left and their account was removed from the repo, taking the token with it. Reconnect with an account that can write to it — ideally a dedicated one.
• The repository was renamed, archived, or deleted. Update the selected owner/repo or point the integration at a live repo.
• Connect is blocked with a plan-limit message. Your plan's integration limit has been reached — remove an unused integration or upgrade your plan.