Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

feat: enhance GitHub integration documentation

Andrej Acevskifc4ccbfbd7ff
diff --git a/README.md b/README.md
index 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.mdx
index 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 Organizations
If 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 organization
3. 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 file
diff --git a/apps/docs/content/docs/core/integrations/github/setup.mdx b/apps/docs/content/docs/core/integrations/github/setup.mdx
index 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 Issues
Double-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 Steps
Now 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.mdx
index 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 Integration
diff --git a/apps/docs/next-env.d.ts b/apps/docs/next-env.d.ts
index 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.