⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
feat: enhance GitHub integration documentation
Andrej Acevskifc4ccbfbd7ff
diff --git a/README.md b/README.mdindex 0e9adc82b..b553965db 100644--- a/README.md+++ b/README.md@@ -27,7 +27,9 @@<h1 align="center">All you need. Nothing you don't.</h1>-<p align="center">Project management that gets out of your way so you can focus on building great products.</p>+<p align="center">+ <img src="https://assets.kaneo.app/readme.png" alt="Kaneo Dashboard" />+</p>## Why Kaneo?diff --git a/apps/docs/content/docs/core/integrations/github/configuration.mdx b/apps/docs/content/docs/core/integrations/github/configuration.mdxindex 5ae8671c9..66e722b18 100644--- a/apps/docs/content/docs/core/integrations/github/configuration.mdx+++ b/apps/docs/content/docs/core/integrations/github/configuration.mdx@@ -182,32 +182,113 @@ Once connected, new tasks created in this project will automatically generate Gi## Testing the Integration-After connecting a repository, test the integration:+After connecting a repository, test the integration thoroughly:<Steps><Step>-**Create a Test Task**+**Test Task to Issue Creation**Create a new task in your connected Kaneo project with:- A clear title- A description- Set priority and status++Navigate to your GitHub repository and verify:+- A new issue was created+- The issue has `priority:*` and `status:*` labels+- A comment links back to the Kaneo task</Step><Step>-**Check GitHub**+**Test Automatic Status Transitions**-Navigate to your connected GitHub repository and check if:-- A new issue was created-- The issue title starts with `[Kaneo]`-- The issue has appropriate labels (`kaneo`, `priority:*`, `status:*`)-- The issue body contains task details+Test branch-based workflow:+1. Note your task number (e.g., `PROJ-123`)+2. Create and push a branch matching the pattern (e.g., `proj-123`)+3. Verify the task moves to "in-progress"+4. Open a PR from that branch+5. Verify the task moves to "in-review"+6. Merge the PR+7. Verify the task moves to "done"++<Callout type="info">+Default branch pattern is `{slug}-{number}`. You can customize this in project settings.+</Callout>+</Step>++<Step>+**Test Issue to Task Sync**++In GitHub:+1. Create a new issue+2. Add labels like `priority:high` or `status:in-progress`++In Kaneo:+- Verify a task was created from the issue+- Check that priority and status match the labels+- Confirm the task links to the GitHub issue+</Step>++<Step>+**Test Label Synchronization**++Test both directions:+1. Change task priority in Kaneo → Check issue labels in GitHub+2. Add/remove labels in GitHub → Check task in Kaneo+3. Change task status in Kaneo → Check if issue is closed/reopened</Step></Steps>## Advanced Configuration+### Branch Naming Patterns++Configure how Kaneo matches branches to tasks in your project's GitHub integration settings:++**Predefined Patterns:**+- `{slug}-{number}` (default) - e.g., `proj-123`+- `{slug}-{number}-{title}` - e.g., `proj-123-fix-bug`+- `{number}` - e.g., `123`+- `{number}-{title}` - e.g., `123-fix-bug`+- `feature/{slug}-{number}` - e.g., `feature/proj-123`+- `fix/{slug}-{number}` - e.g., `fix/proj-123`++**Custom Regex:**+You can also provide a custom regex pattern for more complex matching.++<Callout type="tip">+The `{slug}` variable is your project's slug (case-insensitive), `{number}` is the task number, and `{title}` is an optional slug of the task title.+</Callout>++### Status Transition Configuration++Customize when tasks automatically change status:++| Event | Default Status | Customizable |+|-------|---------------|--------------|+| Branch Push | `in-progress` | ✅ |+| PR Opened | `in-review` | ✅ |+| PR Merged | `done` | ✅ |++Configure these in your project's GitHub integration settings to match your workflow.++<Callout type="warn">+Status transitions only apply if the task is not already in "done" status. This prevents accidentally reopening completed tasks.+</Callout>++### Label Synchronization++Kaneo automatically creates and syncs these label types:++**System Labels** (managed automatically):+- `priority:low`, `priority:medium`, `priority:high`, `priority:urgent`+- `status:to-do`, `status:in-progress`, `status:in-review`, `status:done`, `status:planned`, `status:archived`++**Custom Labels:**+- Any labels added to GitHub issues (not starting with `priority:` or `status:`) are synced to Kaneo+- Labels added in Kaneo can be synced to GitHub (if configured)+### Multiple OrganizationsIf you need to connect repositories from multiple GitHub organizations:@@ -215,14 +296,6 @@ If you need to connect repositories from multiple GitHub organizations:2. Grant appropriate permissions for each organization3. Each Kaneo project can connect to any repository where your app is installed-### Custom Labels-Currently, Kaneo uses these default labels:-- `kaneo` - All issues created by Kaneo-- `priority:high|medium|low` - Based on task priority-- `status:todo|in-progress|done` - Based on task status--Future versions will support custom label configurations.----**Having issues?** Check our [troubleshooting guide](/docs/integrations/github/troubleshooting) for common problems and solutions.\ No newline at end of filediff --git a/apps/docs/content/docs/core/integrations/github/setup.mdx b/apps/docs/content/docs/core/integrations/github/setup.mdxindex 23efbfee9..a9469efce 100644--- a/apps/docs/content/docs/core/integrations/github/setup.mdx+++ b/apps/docs/content/docs/core/integrations/github/setup.mdx@@ -10,13 +10,28 @@ This guide walks you through creating and configuring a GitHub App to enable the## Overview-A GitHub App provides secure, granular access to your repositories and allows Kaneo to:-- Create issues automatically when tasks are created-- Access repository metadata for verification-- Receive webhook events for issue synchronization+A GitHub App provides secure, granular access to your repositories and enables powerful bidirectional synchronization between Kaneo and GitHub:++**Task to GitHub:**+- Automatically create GitHub issues when you create tasks+- Update issue status and priority labels when you change tasks+- Add comments linking to Kaneo tasks+- Close/reopen issues based on task status changes++**GitHub to Kaneo:**+- Create tasks from GitHub issues+- Sync issue labels (priority, status) to task properties+- Link pull requests to tasks automatically+- Update task status based on branch activity (push, PR open/merge)+- Sync GitHub labels to Kaneo task labels++**Automatic Status Transitions:**+- Branch push → Move task to "in-progress"+- PR opened → Move task to "in-review"+- PR merged → Move task to "done"<Callout type="info">-GitHub Apps are more secure than personal access tokens and provide better permission control.+GitHub Apps are more secure than personal access tokens and provide fine-grained permission control.</Callout><Callout type="error">@@ -55,12 +70,17 @@ Configure the following permissions:| Permission | Access | Purpose ||------------|---------|---------|-| **Issues** | Read & Write | Create and update issues |-| **Metadata** | Read | Access repository information |-| **Contents** | Read | Access repository metadata |+| **Issues** | Read & Write | Create issues, add/remove labels, create comments, close/reopen issues |+| **Pull Requests** | Read | Link pull requests to tasks and track PR status |+| **Metadata** | Read | Access repository information and verify installation |+| **Contents** | Read | Track branch pushes and associate commits with tasks |<Callout type="error">-**Critical**: Make sure to grant **Write** access to Issues - this is required for creating issues automatically.+**Critical**: Make sure to grant **Write** access to Issues - this is required for the integration to work properly.+</Callout>++<Callout type="info">+Pull Requests permission is optional but recommended for full integration features. Without it, you won't be able to automatically link PRs to tasks or track PR status changes.</Callout></Step>@@ -69,15 +89,25 @@ Configure the following permissions:**This step is required for proper integration.** Subscribe to these events:-- **Issues** - To track when issues are created, updated, or closed-- **Issue Comments** - To track comments on issues+- **Issues** - To sync issues with tasks (opened, edited, closed, labeled, unlabeled)+- **Issue comments** - To track comments on linked issues+- **Pull requests** - To link PRs to tasks and update task status (opened, closed, reopened, merged)+- **Push** - To automatically update task status based on branch activity<Callout type="error">-**Required**: You must subscribe to **Issues** events for the integration to work properly. This enables bidirectional synchronization between Kaneo tasks and GitHub issues.+**Required**: You must subscribe to **Issues** events for bidirectional synchronization to work.</Callout><Callout type="info">-These webhook events enable real-time synchronization between your Kaneo tasks and GitHub issues.+**Recommended**: Subscribe to all four event types for full integration features:+- **Issues**: Creates tasks from issues and syncs status/labels+- **Issue comments**: Tracks GitHub discussions+- **Pull requests**: Auto-updates task status when PRs are opened/merged+- **Push**: Moves tasks to "in-progress" when branches are pushed+</Callout>++<Callout type="warn">+Without **Push** and **Pull requests** events, automatic status transitions won't work (e.g., moving tasks to "in-progress" on branch push or "done" on PR merge).</Callout></Step>@@ -176,9 +206,16 @@ Ensure your Kaneo instance is:### Permission IssuesDouble-check that you've granted:- **Write** access to Issues (not just Read)+- **Read** access to Pull Requests (for PR linking)- **Read** access to Metadata and Contents- Selected the correct repositories during installation+### Webhook Events Not Working+If automatic synchronization isn't happening:+- Verify all webhook events are subscribed (Issues, Issue comments, Pull requests, Push)+- Check webhook deliveries in GitHub App settings for failed deliveries+- Ensure your webhook URL is publicly accessible and using HTTPS+## Next StepsNow that your GitHub App is created and configured:diff --git a/apps/docs/content/docs/core/integrations/github/troubleshooting.mdx b/apps/docs/content/docs/core/integrations/github/troubleshooting.mdxindex 2751e54f8..1aa1f445b 100644--- a/apps/docs/content/docs/core/integrations/github/troubleshooting.mdx+++ b/apps/docs/content/docs/core/integrations/github/troubleshooting.mdx@@ -50,14 +50,18 @@ Use the "Browse Repositories" feature in Kaneo to see which repositories your ap**Solutions**:1. **Update App Permissions**- Go to your [GitHub App settings](https://github.com/settings/developers)- - Edit your app and check permissions:- - **Issues**: Must have **Write** access (not just Read)- - **Metadata**: Must have **Read** access- - **Contents**: Must have **Read** access+ - Edit your app and verify these permissions:+ - **Issues**: Must have **Write** access (for creating/updating issues, adding labels, posting comments)+ - **Pull Requests**: Must have **Read** access (for linking PRs to tasks)+ - **Metadata**: Must have **Read** access (for repository information)+ - **Contents**: Must have **Read** access (for tracking branch pushes)2. **Update Installation**- After changing app permissions, you may need to update the installation- Go to [GitHub App installations](https://github.com/settings/installations)+ - Click "Configure" on your Kaneo app+ - Review and accept the new permissions+ - Go to [GitHub App installations](https://github.com/settings/installations)- Click "Configure" next to your app- Review and accept any permission changes@@ -173,6 +177,79 @@ Make sure your private key doesn't have any extra characters or missing newlines- If you changed the secret, update the environment variable and restart- Generate a new secret if there are persistent issues+### Automatic Status Transitions Not Working++**Problem**: Tasks aren't automatically updating when you push branches or open/merge PRs.++**Symptoms**:+- Task stays in "to-do" after pushing a branch+- Task doesn't move to "in-review" when PR is opened+- Task doesn't move to "done" when PR is merged++**Solutions**:+1. **Verify Webhook Subscriptions**+ - Go to your [GitHub App settings](https://github.com/settings/developers)+ - Check the "Webhook" section and verify these events are subscribed:+ - **Push** - For branch-based status transitions+ - **Pull requests** - For PR-based status transitions+ - If missing, add them and save++2. **Check Pull Requests Permission**+ - Ensure your app has **Read** access to Pull Requests+ - Without this permission, PR events won't work+ - Update the permission if needed and reinstall the app++3. **Verify Branch Naming Pattern**+ - Your branch name must match the configured pattern (default: `{slug}-{number}`)+ - Example: For task `PROJ-123`, use branch `proj-123` or `PROJ-123`+ - Check your project's GitHub integration settings for the configured pattern++4. **Check Status Transition Configuration**+ - Verify your status transition settings in the project GitHub integration+ - Default transitions:+ - Branch push → `in-progress`+ - PR opened → `in-review`+ - PR merged → `done`+ - These can be customized per project++5. **Review Webhook Delivery Logs**+ - In GitHub App settings → Advanced tab+ - Check if Push and Pull request events are being delivered+ - Look for successful 200 responses++<Callout type="tip">+Test the automatic transitions by:+1. Creating a task (e.g., `PROJ-123`)+2. Creating a branch named `proj-123` and pushing it+3. Verify the task moves to "in-progress"+4. Opening a PR from that branch+5. Verify the task moves to "in-review"+</Callout>++### Issue Label Synchronization Issues++**Problem**: Labels aren't syncing between Kaneo and GitHub.++**Symptoms**:+- Changing priority in Kaneo doesn't update GitHub labels+- Adding labels in GitHub doesn't reflect in Kaneo+- Labels have wrong colors or formats++**Solutions**:+1. **Check Label Format**+ - System labels must use the format: `priority:{level}` or `status:{status}`+ - Valid priority labels: `priority:low`, `priority:medium`, `priority:high`, `priority:urgent`+ - Valid status labels: `status:to-do`, `status:in-progress`, `status:in-review`, `status:done`++2. **Verify Issues Write Permission**+ - Label management requires **Write** access to Issues+ - Check your GitHub App permissions+ - Update and reinstall if needed++3. **Check Webhook Events**+ - Ensure **Issues** events are subscribed (especially "labeled" and "unlabeled")+ - Without these, label changes from GitHub won't sync to Kaneo+## Testing and Debugging### Testing the Integrationdiff --git a/apps/docs/next-env.d.ts b/apps/docs/next-env.d.tsindex c4b7818fb..9edff1c7c 100644--- a/apps/docs/next-env.d.ts+++ b/apps/docs/next-env.d.ts@@ -1,6 +1,6 @@/// <reference types="next" />/// <reference types="next/image-types/global" />-import "./.next/dev/types/routes.d.ts";+import "./.next/types/routes.d.ts";// NOTE: This file should not be edited// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.