# How to Report a Bug in PI Desktop: Complete Guide to Built-in GitHub Integration

> Easily report bugs in PI Desktop using the built-in GitHub integration. Follow our complete guide to submit issues quickly and efficiently, improving the software for everyone.

- Repository: [Lan/PI-Desktop](https://github.com/vastsa/PI-Desktop)
- Tags: how-to-guide
- Published: 2026-09-12

---

**PI Desktop provides a built-in feedback mechanism that automatically captures your system environment and opens a pre-filled GitHub issue template when you click "Report a problem" in Settings → Info.**

When you need to **report a bug in PI Desktop**, the application provides a streamlined, Main process-managed workflow that eliminates manual data entry. This Electron-based application (vastsa/PI-Desktop) automatically gathers version details, operating system, and architecture information to ensure every submission contains the context developers need for reproduction.

## Reporting a Bug Through the PI Desktop Interface

The most direct way to **report a bug in PI Desktop** is through the Settings menu. Navigate to **Settings → Info** and click the **Report a problem** button. This triggers the Main process to collect runtime data and redirect your default browser to GitHub's issue creator with all fields pre-populated.

## Technical Architecture of the Bug Reporting System

According to the [`docs/spec/06-delivery/03-ai-development-workflow.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/06-delivery/03-ai-development-workflow.md) specification, PI Desktop implements a **Main-owned GitHub issue feedback** pattern. This design keeps the feedback intake under strict control of Electron's Main process, preventing renderer-side manipulation of destination URLs and ensuring data integrity.

The workflow relies on three core functions exported from [`packages/shared/src/github-feedback.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/src/github-feedback.ts):

- **`osLabelForFeedback`** – Maps `process.platform` values to human-readable OS labels
- **`formatFeedbackEnvironment`** – Combines version, platform, architecture, protocol version, and host version into a structured string
- **`buildBugReportUrl`** – Constructs the GitHub URL using the [`bug_report.yml`](https://github.com/vastsa/PI-Desktop/blob/main/bug_report.yml) template with query parameters

### Automatic Environment Capture

When you initiate a report, PI Desktop gathers the following **diagnostic metadata**:

- Application version
- Operating system platform and architecture
- Protocol version
- Host component version

This data is formatted into a standardized environment string that appears in the GitHub issue template, ensuring developers can reproduce bugs across different platforms.

### GitHub Template Integration

The target template resides at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/vastsa/PI-Desktop/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml). The `buildBugReportUrl` function appends URL parameters including `app-version`, `os`, and `environment` to pre-fill this template. Electron's `shell.openExternal` then launches your browser to this constructed URL, presenting a ready-to-submit issue form.

## Programmatically Creating Bug Reports

Developers and advanced users can generate bug report URLs programmatically using the same utilities that power the UI. This is useful for building custom feedback tools or documentation:

```typescript
import { buildBugReportUrl, osLabelForFeedback, formatFeedbackEnvironment } from '../packages/shared/src/github-feedback';
import { shell } from 'electron';

const feedbackInfo = {
  version: '0.13.3',
  platform: process.platform,
  arch: process.arch,
  protocolVersion: 12,
  hostVersion: '0.13.3'
};

const bugUrl = buildBugReportUrl(feedbackInfo);
shell.openExternal(bugUrl);

```

To retrieve the raw URL without opening a browser—for example, to display it in logs or documentation—call the function directly:

```typescript
console.log(buildBugReportUrl({
  version: '0.13.3',
  platform: 'darwin',
  arch: 'arm64',
  protocolVersion: 12,
  hostVersion: '0.13.3'
}));
// Outputs: https://github.com/vastsa/PI-Desktop/issues/new?template=bug_report.yml&app-version=0.13.3&os=macOS&environment=PI-Desktop%200.13.3%20·%20darwin%20arm64%20·%20protocol%2012%20·%20host%200.13.3

```

## Summary

- PI Desktop's bug reporting is accessible via **Settings → Info → Report a problem**
- The system automatically captures version, OS, architecture, protocol, and host data
- The workflow is controlled by Electron's Main process for security, as specified in [`docs/spec/06-delivery/03-ai-development-workflow.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/06-delivery/03-ai-development-workflow.md)
- Helper functions in [`packages/shared/src/github-feedback.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/src/github-feedback.ts) handle URL construction and environment formatting
- Reports use the [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/vastsa/PI-Desktop/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) template for consistent structure

## Frequently Asked Questions

### Where is the "Report a problem" button located in PI Desktop?

The **Report a problem** button is located in **Settings → Info**. Clicking it initiates the Main process workflow that opens a pre-filled GitHub issue template in your default browser.

### What system information is automatically included when reporting a bug in PI Desktop?

The report automatically includes your **app version**, **operating system** (platform and architecture), **protocol version**, and **host version**. These values are formatted by the `formatFeedbackEnvironment` function in [`packages/shared/src/github-feedback.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/src/github-feedback.ts) to ensure developers have complete reproduction context.

### Can I generate a bug report URL without clicking the UI button?

Yes. Import `buildBugReportUrl` from [`packages/shared/src/github-feedback.ts`](https://github.com/vastsa/PI-Desktop/blob/main/packages/shared/src/github-feedback.ts) and pass an object containing your version, platform, arch, protocolVersion, and hostVersion. This returns a GitHub URL that you can open manually or display in documentation.

### Why is the bug reporting logic handled by the Main process in PI Desktop?

The Main process ownership, documented in [`docs/spec/06-delivery/03-ai-development-workflow.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/spec/06-delivery/03-ai-development-workflow.md), prevents renderer-side code from manipulating the destination URL or feedback data. This security model ensures that bug reports cannot be intercepted or modified by potentially compromised renderer processes, maintaining the integrity of the feedback channel.