# How to Report a Bug in Kaneo: Complete Guide to GitHub Issues and Templates

> Learn how to report a bug in Kaneo efficiently using GitHub Issues and templates. Follow our guide for clear bug reporting and faster resolution.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-02

---

**The recommended way to report a bug in Kaneo is through a GitHub Issue using the built-in Bug Report template at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/usekaneo/kaneo/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml), which auto-labels submissions with `bug` and triggers team notifications via GitHub Actions.**

Kaneo is an open-source project management platform built as a **pnpm monorepo** with three core applications: a Hono-based backend API (`apps/api`), a React/Vite frontend (`apps/web`), and a documentation site (`apps/docs`). Understanding how to report a bug in Kaneo properly ensures maintainers can quickly reproduce, diagnose, and resolve issues across these interconnected codebases.

## Where to Report Bugs in Kaneo

### GitHub Issues: The Primary Channel

Kaneo uses **GitHub Issues** as its exclusive bug-tracking system. Unlike email or informal channels, issues are integrated directly with the repository's workflow, version control, and automated tooling.

The repository provides a structured **Bug Report template** that enforces consistent reporting standards. This template lives at [[`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/usekaneo/kaneo/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml)](https://github.com/usekaneo/kaneo/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) and is automatically presented when you select "Bug Report" from the new issue menu.

## Step-by-Step: Submitting a Bug Report

### Step 1: Navigate to the Issue Template

1. Go to the [Kaneo repository issues page](https://github.com/usekaneo/kaneo/issues)
2. Click **"New issue"**
3. Select **"Bug Report"** from the template options

The [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/usekaneo/kaneo/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) file defines the form structure, including required fields and automatic labeling.

### Step 2: Complete All Required Fields

The template enforces five mandatory sections:

| Field | Purpose |
|-------|---------|
| **Description** | Concise summary of the unexpected behavior |
| **Steps to Reproduce** | Ordered list anyone can follow to trigger the bug |
| **Expected Result** | Correct behavior under normal conditions |
| **Actual Result** | What actually happens when the bug occurs |
| **Environment** | Version, deployment method, browser, OS |

### Step 3: Add Optional Context

- **Screenshots** – Visual evidence of UI bugs, particularly helpful for issues in `apps/web/src/**` components
- **Additional Context** – Network logs, console errors, or edge cases

### Step 4: Submit and Track

Upon submission, the issue is automatically:

- Labeled with `bug` (defined in the template's `labels:` field)
- Processed by [[`.github/workflows/issue-notify.yml`](https://github.com/usekaneo/kaneo/blob/main/.github/workflows/issue-notify.yml)](https://github.com/usekaneo/kaneo/blob/main/.github/workflows/issue-notify.yml), which notifies the team via Discord
- Added to project boards for triage

## Bug Report Example

Here's a complete, properly formatted bug report following Kaneo's template structure:

```yaml
name: "[Bug]: Task list does not persist after reload"
description: |
  The task list on the dashboard disappears after I refresh the page.
reproduction_steps: |
  1. Log in as a regular user.
  2. Create a new task in any project.
  3. Refresh the browser.
  4. Observe that the newly created task is missing.
expected_result: |
  The newly created task should remain visible after a page reload.
actual_result: |
  The task disappears; the API returns a 200 OK response but the UI shows an empty list.
environment: |
  - Kaneo Version: 1.2.3
  - Deployment Method: Docker
  - Browser: Chrome 121
  - OS: macOS Ventura
screenshots: |
  (attach PNG)
additional_context: |
  No custom plugins installed. The issue occurs on both local dev (pnpm dev) and Docker deployments.

```

## Reporting Bugs Programmatically with GitHub CLI

For developers who prefer command-line workflows, use the `gh` CLI to create issues with identical structure:

```bash
gh issue create \
  --title "[Bug]: Task list does not persist after reload" \
  --body "$(cat <<'EOF'
**Bug Description**
The task list on the dashboard disappears after I refresh the page.

**Steps To Reproduce**
1. Log in as a regular user.
2. Create a new task in any project.
3. Refresh the browser.
4. Observe that the newly created task is missing.

**Expected Result**
The newly created task should remain visible after a page reload.

**Actual Result**
The task disappears; the API returns a 200 OK response but the UI shows an empty list.

**Environment**
- Kaneo Version: 1.2.3
- Deployment Method: Docker
- Browser: Chrome 121
- OS: macOS Ventura
EOF
)" \
  --label bug

```

## Contributing a Fix After Reporting

If you want to resolve the bug yourself, follow Kaneo's contribution workflow documented in [[`CONTRIBUTING.md`](https://github.com/usekaneo/kaneo/blob/main/CONTRIBUTING.md)](https://github.com/usekaneo/kaneo/blob/main/CONTRIBUTING.md#making-your-first-contribution):

1. **Fork and branch**: Create `fix/<description>` from `main`
2. **Locate relevant code**: Backend bugs typically involve `apps/api/src/**` route handlers; frontend bugs reside in `apps/web/src/**` components
3. **Test your changes**: Run `pnpm test` for unit tests and `pnpm test:integration` for integration coverage
4. **Commit conventionally**: Use `fix: <short description>` format
5. **Reference the issue**: Include `Closes #<issue_number>` in your pull request description

The **Contributing** guide's *"Found a bug?"* section explicitly directs reporters through this process, ensuring no duplicate work and clear issue-to-PR traceability.

## Key Files for Bug Reporters

| File | Purpose |
|------|---------|
| [[`CONTRIBUTING.md`](https://github.com/usekaneo/kaneo/blob/main/CONTRIBUTING.md)](https://github.com/usekaneo/kaneo/blob/main/CONTRIBUTING.md) | Complete contribution workflow, including bug discovery and reporting procedures |
| [[`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/usekaneo/kaneo/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml)](https://github.com/usekaneo/kaneo/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) | Structured form defining required fields and auto-labeling |
| [[`.github/workflows/issue-notify.yml`](https://github.com/usekaneo/kaneo/blob/main/.github/workflows/issue-notify.yml)](https://github.com/usekaneo/kaneo/blob/main/.github/workflows/issue-notify.yml) | Automation that routes new issues to maintainers |
| `apps/api/src/**` | Backend source where API-related bugs originate |
| `apps/web/src/**` | Frontend source where UI-related bugs originate |

## Summary

- Navigate to **GitHub Issues** and select the **Bug Report** template
- Complete all **five required fields**: Description, Steps to Reproduce, Expected Result, Actual Result, and Environment
- Use optional **Screenshots** and **Additional Context** to accelerate triage
- Submitting triggers automatic `bug` labeling and **Discord notifications** via GitHub Actions
- Reference [[`CONTRIBUTING.md`](https://github.com/usekaneo/kaneo/blob/main/CONTRIBUTING.md)](https://github.com/usekaneo/kaneo/blob/main/CONTRIBUTING.md) if you plan to submit a fix yourself

## Frequently Asked Questions

### What information is absolutely required in a Kaneo bug report?

The [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/usekaneo/kaneo/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) template enforces **Description**, **Steps to Reproduce**, **Expected Result**, **Actual Result**, and **Environment** as mandatory fields. You cannot submit the issue without completing these sections.

### Does Kaneo accept bug reports via email or Discord?

No. Kaneo routes all bug reports exclusively through **GitHub Issues** to ensure traceability, version control integration, and automated workflow processing. The [[`.github/workflows/issue-notify.yml`](https://github.com/usekaneo/kaneo/blob/main/.github/workflows/issue-notify.yml)](https://github.com/usekaneo/kaneo/blob/main/.github/workflows/issue-notify.yml) does push notifications to Discord, but submissions must originate from GitHub.

### How do I know if my bug is in the API or the frontend?

Check the **Environment** and **Actual Result** fields. API bugs typically manifest as unexpected HTTP responses, authentication failures, or data persistence issues in `apps/api/src/**`. Frontend bugs involve rendering problems, state management issues, or UI interactions in `apps/web/src/**`. Include network logs and console output in **Additional Context** to help maintainers locate the source quickly.

### What happens after I submit a bug report?

The issue receives the `bug` label automatically, triggers the notification workflow in [[`.github/workflows/issue-notify.yml`](https://github.com/usekaneo/kaneo/blob/main/.github/workflows/issue-notify.yml)](https://github.com/usekaneo/kaneo/blob/main/.github/workflows/issue-notify.yml), and appears on the maintainers' project board for triage. Response times vary by severity and reproducibility—clear, complete reports with minimal reproduction steps are prioritized.