# Filing reports to GitHub

You can file a report as an issue in your own GitHub repository, from the report page. Filing is one way and on request: nothing is filed automatically, and nothing comes back from GitHub. Closing the issue in GitHub does not change the report in Userreact.

Setting up GitHub requires the **owner** or **admin** role. Members can file reports once it is set up.

## Setting it up

1. Open **Sites**, click the site, and in the **Issue tracker** card click **Set it up**.
2. In the **GitHub** card click **Connect GitHub**. GitHub asks you to install the Userreact app; choose the repositories it may see.
   - If your GitHub organization requires approval, you see "GitHub is waiting for an organization owner to approve the installation." Come back once an owner has approved it.
3. In the **Repository** card, choose the repository reports should be filed into. Public repositories are marked "(public)".
4. Optionally set **Labels for bugs** (default `bug`) and **Labels for suggestions** (default `enhancement`), up to 10 each. A label that does not exist on the repository is created.
5. Click **Save**.

To change repository later, use **Change repository** on the site page. **Manage on GitHub** changes which repositories the app can see.

## Reporter name and email

By default the issue does not include the reporter's name or email; it carries an anonymous reporter id and a link back to the report in Userreact. In the **Reporter identity** card you can switch on **Include the reporter's name and email in the issue**. This is not available for a public repository, because an issue there is world-readable and indexed.

## Filing a report

On the report page, click **Create an issue**. When it is done you see "Filed as #123" and a link to the issue.

The issue contains the report text; the page, page title, site, date, reporter and a link to the report; the browser details; and collapsible console errors and failed requests. Screenshots are not uploaded to GitHub: the issue says how many are attached, with a link to view them in Userreact.

## Problems

- "Connect a repository for this site before filing issues.": no repository is chosen for this site yet. A member sees "Ask an owner or admin to set it up."
- "GitHub is no longer connected. Reconnect it in the site settings.": the app was uninstalled or lost access. Use **Reconnect GitHub**.
- "GitHub asked us to slow down.": GitHub's rate limit. Try again at the time shown.
- If filing failed, click **Try again**.