External Services Kaneo Can Integrate With: Complete Plugin Architecture Guide

Kaneo supports six external service integrations—Slack, Discord, Telegram, GitHub, Gitea, and generic webhooks—implemented via a modular plugin system that exposes RESTful configuration endpoints.

Kaneo is an open-source project management platform designed to automate task workflows through external service integrations. Understanding which external services Kaneo can integrate with enables teams to synchronize project updates across their existing communication and development toolchains. The integration architecture resides in the usekaneo/kaneo repository under apps/api/src/plugins/.

Supported External Service Integrations

Kaneo’s plugin architecture supports six distinct external services, each providing specific webhook capabilities and event-driven synchronization. All plugins follow a consistent registration pattern defined in the central plugin index.

Slack

The Slack integration sends task-related events—including creation, status changes, and comments—to a designated workspace via incoming webhooks.

• Entry Point: apps/api/src/plugins/slack/index.ts
• Configuration: apps/api/src/plugins/slack/config.ts
• Functionality: Posts real-time task updates to specified channels using Slack's incoming webhook protocol.

Discord

The Discord integration mirrors the Slack functionality, delivering the same task-event flow to Discord channels.

• Entry Point: apps/api/src/plugins/discord/index.ts
• Mechanism: Utilizes Discord webhooks to broadcast task notifications to server channels.

Telegram

The Telegram integration posts task updates directly to Telegram chats or bot conversations.

• Entry Point: apps/api/src/plugins/telegram/index.ts
• Use Case: Enables mobile notifications and team chat synchronization through Telegram's bot API.

GitHub

The GitHub integration provides bidirectional synchronization between Kaneo tasks and GitHub issues or pull requests.

• Entry Point: apps/api/src/plugins/github/index.ts
• Capabilities: Reacts to GitHub webhooks and updates issue status or labels based on Kaneo activity.
• Configuration: Requires a GitHub App installation ID and repository identifier stored in apps/api/src/plugins/github/config.ts.

Gitea

The Gitea integration offers the same feature set as the GitHub plugin but targets self-hosted Gitea repositories.

• Entry Point: apps/api/src/plugins/gitea/index.ts
• Compatibility: Supports Gitea-specific webhook payloads for teams using self-hosted Git infrastructure.

Generic Webhook

The Generic Webhook integration serves as a catch-all endpoint for any external service capable of receiving HTTP POST requests.

• Entry Point: apps/api/src/plugins/generic-webhook/index.ts
• Flexibility: Allows custom integrations with proprietary systems, CI/CD pipelines, or unsupported third-party tools.
• Security: Supports optional HMAC secret verification for payload authentication.

Plugin Architecture and Registration

All external service integrations are registered through a centralized initialization system. The initializePlugins() function in apps/api/src/plugins/index.ts calls registerPlugin() for each service, executing service-specific bootstrap logic such as initializeGitHubPlugin().

The plugin registry maintains a lookup map in apps/api/src/plugins/registry.ts, providing utility functions for the rest of the system to resolve active integrations dynamically. This modular design ensures that each external service operates as an isolated plugin while sharing a common interface for event broadcasting.

Configuring Integrations via the API

Kaneo exposes typed REST endpoints for creating and managing integrations. The following examples use the @kaneo/libs client, though standard fetch requests work identically.

Creating a Slack Integration

import { kaneoClient } from '@kaneo/libs';

// projectId refers to the workspace project receiving the integration
await kaneoClient.post(`/api/slack-integration/project/${projectId}`, {
  config: {
    webhookUrl: 'https://hooks.slack.com/services/XXX/YYY/ZZZ',
    channel: '#kaneo-updates',
  },
});

This endpoint is handled in apps/api/src/plugins/slack/config.ts and documented in the OpenAPI specification.

Creating a GitHub Integration

await kaneoClient.post(`/api/github-integration/project/${projectId}`, {
  config: {
    installationId: 123456,          // GitHub App installation ID
    repository: 'owner/repo',
    // Optional: scopes, labels mapping, etc.
  },
});

Configuration logic resides in apps/api/src/plugins/github/config.ts.

Creating a Generic Webhook Integration

await kaneoClient.post(`/api/generic-webhook-integration/project/${projectId}`, {
  config: {
    url: 'https://example.com/kaneo-webhook',
    secret: 'super-secret',   // Optional HMAC secret for verification
  },
});

See apps/api/src/plugins/generic-webhook/config.ts for implementation details.

Listing All Project Integrations

const integrations = await kaneoClient.get(
  `/api/integrations/project/${projectId}`
);
console.log(integrations);

The generic integration list endpoint is defined in apps/api/src/plugins/registry.ts.

Summary

• Kaneo integrates with six external services: Slack, Discord, Telegram, GitHub, Gitea, and generic webhooks.
• Each integration is implemented as a modular plugin under apps/api/src/plugins/.
• Plugin registration occurs centrally in apps/api/src/plugins/index.ts via initializePlugins().
• The GitHub and Gitea plugins support bidirectional synchronization with issue and PR data.
• The Generic Webhook plugin enables custom integrations with any HTTP-capable service.
• Configuration endpoints follow the pattern /api/{service}-integration/project/{projectId}.

Frequently Asked Questions

Which external messaging platforms does Kaneo support?

Kaneo natively supports Slack, Discord, and Telegram for real-time task notifications. Each messaging integration uses service-specific webhook implementations located in apps/api/src/plugins/slack/, apps/api/src/plugins/discord/, and apps/api/src/plugins/telegram/ respectively.

How does Kaneo handle plugin initialization internally?

Kaneo calls initializePlugins() from apps/api/src/plugins/index.ts during API startup. This function iterates through registered services and executes bootstrap logic—such as initializeGitHubPlugin()—to prepare webhook handlers and configuration routes for each external service.

Can Kaneo integrate with self-hosted Git repositories?

Yes. While the GitHub plugin targets github.com, the Gitea plugin in apps/api/src/plugins/gitea/index.ts provides identical functionality for self-hosted Gitea instances. Additionally, the Generic Webhook plugin allows custom integrations with other self-hosted Git platforms.

What distinguishes the Generic Webhook from native service integrations?

The Generic Webhook plugin (apps/api/src/plugins/generic-webhook/index.ts) acts as a universal adapter for any external service that accepts HTTP POST requests. Unlike native plugins that format payloads for specific APIs (like Slack blocks or GitHub issue updates), the generic webhook forwards raw task events to a user-specified URL with optional HMAC signature verification.

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