# How to Report a Bug in holaOS: Complete Guide to GitHub Issues and Security Disclosure

> Learn how to report a bug in holaOS by submitting a GitHub issue. Find instructions for bug reports and security disclosures to help improve holaOS.

- Repository: [holaboss.ai/holaOS](https://github.com/holaboss-ai/holaOS)
- Tags: how-to-guide
- Published: 2026-08-15

---

**To report a bug in holaOS, open a new GitHub issue using the Bug Report template at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/holaboss-ai/holaOS/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml), fill in all environment details and reproduction steps, and submit; for security vulnerabilities, email `admin@holaboss.ai` instead.**

The holaOS repository by holaboss-ai uses a structured GitHub workflow to ensure every bug report contains the context needed for maintainers to reproduce and fix issues efficiently. Whether you have encountered a crash in the desktop runtime or unexpected behavior in a HolaApp, following the official reporting process helps the team prioritize and resolve problems faster.

## Using the GitHub Issue Template

The primary method to report a bug in holaOS starts with the repository's structured issue templates. This standardized format eliminates guesswork and ensures you provide the technical details maintainers need.

### Accessing the Bug Report Template

Navigate to the repository's Issues tab and click **New Issue**. Select the **Bug Report** template, which is defined in [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/holaboss-ai/holaOS/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml). This YAML-formatted template automatically renders form fields in the GitHub interface, prompting you for specific information rather than requiring manual markdown formatting.

### Required Information Fields

A high-quality bug report requires complete environment details and clear reproduction steps. According to the source code analysis, you must provide:

- **Operating system and architecture** (macOS Apple Silicon/Intel, Windows, or Linux)
- **holaOS version** (run `npm run desktop:version` or note the Git SHA of your current commit)
- **Detailed reproduction steps** with numbered instructions
- **Expected vs. actual behavior** descriptions
- **Screenshots or log excerpts** from relevant files like [`runtime/harness-host/src/pi-search-tool.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harness-host/src/pi-search-tool.ts) or [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/scripts/install.sh)
- **Clean install confirmation** indicating whether the issue persists on a fresh installation

## Reporting Security Vulnerabilities Privately

Security-sensitive bugs—such as potential credential exposure or runtime vulnerabilities—must never be reported via public GitHub issues. As documented in the README.md (lines 222-224) and the [`SECURITY.md`](https://github.com/holaboss-ai/holaOS/blob/main/SECURITY.md) file, you should send security disclosures directly to `admin@holaboss.ai`. This private channel allows the maintainers to patch vulnerabilities before public disclosure, following responsible security practices.

## Automating Bug Reports with the GitHub API

If you maintain automated testing pipelines or prefer scripting your workflow, you can programmatically create holaOS bug reports using the GitHub REST API. You will need a personal access token with `repo` scope.

The following `curl` command creates an issue with the same structured content required by the manual template:

```bash

# Replace <TOKEN> with a personal access token

curl -X POST \
     -H "Authorization: token <TOKEN>" \
     -H "Accept: application/vnd.github.v3+json" \
     https://api.github.com/repos/holaboss-ai/holaOS/issues \
     -d '{
       "title": "Bug: Unexpected crash on Windows when opening a HolaApp",
       "body": "## Environment\n- OS: Windows 11\n- holaOS version: 0.9.3\n\n## Steps to Reproduce\n1. Open the Notion HolaApp.\n2. Click the **Create** button.\n3. The app crashes with error *XYZ*.\n\n## Expected Behavior\nThe app should open without crashing.\n\n## Actual Behavior\nThe app crashes displaying stack trace …\n",

       "labels": ["bug"]
     }'

```

This programmatic approach ensures consistent labeling and formatting while integrating directly into your incident tracking systems.

## What Happens After You Submit

Once you submit a bug report through GitHub Issues, the holaOS maintainers triage the ticket using repository labels. They may request additional logs from specific source files—such as stack traces originating in [`runtime/harness-host/src/pi-search-tool.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harness-host/src/pi-search-tool.ts) for search-related crashes or installation logs from [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/scripts/install.sh) for setup failures. Security reports sent to `admin@holaboss.ai` receive acknowledgment within 48 hours and proceed through a private disclosure timeline.

## Summary

- **Use the template**: File bug reports via [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/holaboss-ai/holaOS/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) to ensure structured data capture.
- **Include version info**: Always run `npm run desktop:version` to provide exact holaOS commit SHAs or release numbers.
- **Email security bugs**: Send vulnerability reports to `admin@holaboss.ai` rather than public issues.
- **Automate if needed**: Use the GitHub Issues API with proper authentication to create tickets programmatically.
- **Reference source files**: Mention specific paths like [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/scripts/install.sh) or [`runtime/harness-host/src/pi-search-tool.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harness-host/src/pi-search-tool.ts) when relevant to crashes.

## Frequently Asked Questions

### Where is the holaOS bug report template located?

The official bug report template resides at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/holaboss-ai/holaOS/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) in the holaboss-ai/holaOS repository. This YAML file defines the form fields you see when creating a new issue, including dropdowns for OS selection and text areas for reproduction steps.

### How do I report a security vulnerability in holaOS?

Email `admin@holaboss.ai` directly with details of the vulnerability. As specified in the README.md and SECURITY.md files, security-sensitive bugs require private disclosure to prevent exploitation before a patch is available. Do not create public GitHub issues for security problems.

### Can I create holaOS bug reports programmatically?

Yes. Use the GitHub REST API endpoint `POST /repos/holaboss-ai/holaOS/issues` with a personal access token containing `repo` scope. Format the JSON payload to match the Bug Report template structure, including environment details in the body and the "bug" label for proper categorization.

### What version information should I include in a holaOS bug report?

Include the output of `npm run desktop:version` or the specific Git SHA of the commit you are running. This precise version data allows maintainers to correlate your report with the exact state of the codebase in files like [`runtime/harness-host/src/pi-search-tool.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harness-host/src/pi-search-tool.ts) or [`scripts/install.sh`](https://github.com/holaboss-ai/holaOS/blob/main/scripts/install.sh).