# How to Configure Kaneo Integrations for GitHub and Slack

> Learn how to configure Kaneo integrations with GitHub and Slack. Discover Kaneo's layered architecture for seamless external service connections and data management.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-30

---

**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`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/components/project/slack-integration-settings.tsx). For GitHub, this is [`apps/web/src/components/project/github-integration-settings.tsx`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/hooks/mutations/slack-integration/use-slack-integration.ts), while GitHub hooks are split across files like [`use-create-github-integration.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/fetchers/slack-integration/delete-slack-integration.ts).

### Code Example: Creating a Slack Integration

```typescript
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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/fetchers/github-integration/import-github-issues.ts).

### Code Example: Connecting a GitHub Repository

```typescript
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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/components/project/slack-integration-settings.tsx).