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

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, 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) 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
2. Click "New issue"
3. Select "Bug Report" from the template options

The .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), 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:

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:

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#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)	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)	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)	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) 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 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) 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), 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}