How to Configure Kaneo Integrations for GitHub and Slack

Kaneo configures external integrations through a layered architecture where React UI components capture settings, React Query hooks manage mutations, fetcher functions handle HTTP transport, and Hono API controllers validate and persist data to PostgreSQL.

Kaneo is an open-source project management platform that connects external services like GitHub and Slack through a modular integration system. To configure Kaneo integrations, you work with a React-based frontend that communicates via typed client hooks to a Hono API backend. Every integration follows an identical four-layer pattern regardless of the external service.

Understanding the Integration Architecture

Each integration in the usekaneo/kaneo repository implements a consistent flow from user interface to database storage.

The architecture consists of four distinct layers:

• UI Components – Render configuration forms and handle user interactions. For Slack, this is apps/web/src/components/project/slack-integration-settings.tsx. For GitHub, this is apps/web/src/components/project/github-integration-settings.tsx.
• React Query Hooks – Expose typed mutations including useCreate…, useUpdate…, useDelete…, and useGet… operations. Slack integration hooks live in apps/web/src/hooks/mutations/slack-integration/use-slack-integration.ts, while GitHub hooks are split across files like use-create-github-integration.ts.
• Fetcher Functions – Perform HTTP requests to API endpoints. Slack fetchers reside in apps/web/src/fetchers/slack-integration/ (create, update, get, delete), and GitHub fetchers live in apps/web/src/fetchers/github-integration/.
• API Controllers – Hono routes that accept payloads, validate them with Zod, enforce workspace permissions, and store data in PostgreSQL. Controllers are located in apps/api/src/slack-integration/controllers/ and apps/api/src/github-integration/controllers/.

Configuring Slack Integration

Slack integration enables real-time task notifications through incoming webhooks.

Required Data and Validation

To configure Slack, you must provide:

• webhookUrl – Must match the pattern https://hooks.slack.com/services/...
• channelName – Target channel identifier
• Event flags – Boolean toggles for taskCreated, taskStatusChanged, taskPriorityChanged, taskTitleChanged, taskDescriptionChanged, and taskCommentCreated

Validation occurs both client-side using Zod (isValidSlackWebhookUrl) and server-side via API schema validation. The EventToggle helper component in the UI renders these switches, mapping directly to database fields.

Implementation Flow

The configuration workflow proceeds through these stages:

1. Load existing config – The useGetSlackIntegration query fetches stored webhook data and event preferences from fetchers/slack-integration/get-slack-integration.ts.
2. Create connection – Clicking "Connect" triggers useCreateSlackIntegration, which posts to the API via fetchers/slack-integration/create-slack-integration.ts.
3. Update settings – Changing any field (channel name, webhook URL, or event toggles) invokes useUpdateSlackIntegration, sending partial JSON payloads to fetchers/slack-integration/update-slack-integration.ts.
4. Toggle active state – The isActive boolean is updated via the same mutation with a minimal payload { isActive: true|false }.
5. Disconnect – Clicking "Disconnect" calls useDeleteSlackIntegration, which removes stored secrets through fetchers/slack-integration/delete-slack-integration.ts.

Code Example: Creating a Slack Integration

import { useCreateSlackIntegration } from '@/hooks/mutations/slack-integration/use-slack-integration';

const { mutateAsync: createIntegration } = useCreateSlackIntegration();

await createIntegration({
  projectId,
  data: {
    webhookUrl: 'https://hooks.slack.com/services/AAA/BBB/CCC',
    channelName: '#kaneo-updates',
    events: {
      taskCreated: true,
      taskStatusChanged: true,
      taskPriorityChanged: false,
      taskTitleChanged: false,
      taskDescriptionChanged: false,
      taskCommentCreated: true,
    },
  },
});

Configuring GitHub Integration

GitHub integration synchronizes repository issues with Kaneo tasks and supports bidirectional linking.

Repository Setup and Verification

Before storing configuration, Kaneo verifies GitHub App installation status. The UI validates repository inputs using regex patterns (owner allows alphanumerics and hyphens; name allows alphanumerics, dots, underscores, and hyphens).

The verification process:

• Calls useVerifyGithubInstallation, which executes fetchers/github-integration/verify-github-installation.ts
• Returns three critical fields:
  • isInstalled – Whether the GitHub App is present on the repository
  • hasRequiredPermissions – Whether the app can read/write issues
  • missingPermissions – Array of scopes the user must grant

Optional Configuration Features

After successful verification, you can enable additional behaviors:

• Comment-task linking – Setting commentTaskLinkOnGitHubIssue: true makes the integration post comments on GitHub issues containing links back to Kaneo tasks.
• Issue import – Triggering useImportGithubIssues initiates a background job that pulls all open GitHub issues into the current Kaneo project via fetchers/github-integration/import-github-issues.ts.

Code Example: Connecting a GitHub Repository

import { useCreateGithubIntegration } from '@/hooks/mutations/github-integration/use-create-github-integration';
import { useVerifyGithubInstallation } from '@/hooks/mutations/github-integration/use-verify-github-installation';

const { mutateAsync: verifyInstallation } = useVerifyGithubInstallation();
const { mutateAsync: createIntegration } = useCreateGithubIntegration();

const repo = { repositoryOwner: 'octocat', repositoryName: 'hello-world' };

// Verify the app is installed and has needed permissions
const verification = await verifyInstallation({ ...repo, projectId });
if (!verification.isInstalled || !verification.hasRequiredPermissions) {
  // Show error / guide user to install the app
}

// Create the integration
await createIntegration({ projectId, data: repo });

Managing Integration State

Both GitHub and Slack integrations support lifecycle management through standardized mutations.

Updating configuration – Call useUpdateSlackIntegration or useUpdateGithubIntegration with partial JSON payloads to modify specific fields without recreating the integration.

Toggling active status – Send { isActive: false } to temporarily disable notifications without deleting stored credentials.

Deleting integrations – Invoke useDeleteSlackIntegration or the GitHub equivalent to remove webhook secrets and repository links from PostgreSQL permanently.

Summary

• Kaneo uses a four-layer architecture (UI → React Query → Fetchers → API Controllers) for all integrations.
• Slack configuration requires a valid webhook URL and event toggle selections, validated by Zod schemas in apps/web/src/components/project/slack-integration-settings.tsx.
• GitHub configuration requires repository owner/name validation and App installation verification via useVerifyGithubInstallation.
• Mutations follow consistent naming patterns: useCreate…, useUpdate…, useDelete…, and useGet….
• Optional GitHub features include automatic issue import and comment-based task linking.

Frequently Asked Questions

How do I verify my GitHub App has the correct permissions in Kaneo?

Call the useVerifyGithubInstallation hook from apps/web/src/hooks/mutations/github-integration/use-verify-github-installation.ts. This function returns isInstalled, hasRequiredPermissions, and missingPermissions fields. If hasRequiredPermissions is false, the missingPermissions array lists the specific GitHub scopes you need to grant.

Where does Kaneo store integration secrets and webhook URLs?

The Hono API controllers in apps/api/src/slack-integration/controllers/ and apps/api/src/github-integration/controllers/ receive validated payloads and persist them to PostgreSQL. The database stores webhook URLs, repository references, event flags, and active status flags according to the Zod schemas defined in the API layer.

Can I temporarily disable a Slack integration without deleting it?

Yes. Use the useUpdateSlackIntegration hook to send a partial update with { isActive: false }. This toggles the integration off while preserving the webhook URL and event configuration in the database. You can re-enable it later by sending { isActive: true } through the same mutation.

What events can trigger Slack notifications in Kaneo?

The Slack integration supports six event types: taskCreated, taskStatusChanged, taskPriorityChanged, taskTitleChanged, taskDescriptionChanged, and taskCommentCreated. Each maps to a boolean field in the integration model and is rendered in the UI via the EventToggle component in apps/web/src/components/project/slack-integration-settings.tsx.

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