chat-adapter-gitea

Gitea adapter for Chat SDK. Drop-in replacement for @chat-adapter/github. Respond to @mentions in PR and issue comment threads.

The Gitea adapter treats issue and pull request comments as messages, and issues/PRs as threads.

Requires Gitea 1.25+ which provides all the API endpoints needed for full feature parity with the official GitHub adapter.

Installation

pnpm add chat-adapter-gitea

Usage

The adapter auto-detects credentials from GITEA_TOKEN, GITEA_BASE_URL, GITEA_WEBHOOK_SECRET, and GITEA_BOT_USERNAME environment variables:

import { Chat } from "chat";
import { createGiteaAdapter } from "chat-adapter-gitea";

const bot = new Chat({
  userName: "my-bot",
  adapters: {
    gitea: createGiteaAdapter(),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from Gitea!");
});

Authentication

Personal Access Token

1. Go to Settings → Applications → Manage Access Tokens
2. Create a new token with repo and issue scopes
3. Set GITEA_TOKEN environment variable

createGiteaAdapter({
  token: process.env.GITEA_TOKEN!,
  baseUrl: process.env.GITEA_BASE_URL!,
});

Webhook setup

1. Go to repository or organisation Settings → Webhooks → Add Webhook → Gitea
2. Set Target URL to https://your-domain.com/api/webhooks/gitea
3. Set Content Type to application/json (required)
4. Set Secret to match your webhookSecret
5. Select events: Issue Comments, Pull Request Review Comments

// app/api/webhooks/gitea/route.ts (Next.js App Router)
import { bot } from "@/lib/bot";

export async function POST(request: Request) {
  return bot.webhooks.gitea(request);
}

Migrating from @chat-adapter/github

The adapter exposes the same interface and method signatures. Migration requires changing imports and environment variables.

Before (GitHub)

import { createGitHubAdapter } from "@chat-adapter/github";

const bot = new Chat({
  adapters: {
    github: createGitHubAdapter(),
  },
});

After (Gitea)

import { createGiteaAdapter } from "chat-adapter-gitea";

const bot = new Chat({
  adapters: {
    gitea: createGiteaAdapter(),
  },
});

Thread IDs change prefix from github: to gitea: but follow the same format.

Thread model

Gitea has the same three types of comment threads as GitHub:

| Type | Context | Thread ID format | |------|---------|-----------------| | PR-level | PR Conversation tab | gitea:{owner}/{repo}:{prNumber} | | Review comments | PR Files Changed tab | gitea:{owner}/{repo}:{prNumber}:rc:{commentId} | | Issue comments | Issue thread | gitea:{owner}/{repo}:issue:{issueNumber} |

Reactions

Supports the same reaction emoji as GitHub:

| SDK emoji | Gitea reaction | |-----------|----------------| | thumbs_up | +1 | | thumbs_down | -1 | | laugh | laugh | | confused | confused | | heart | heart | | hooray | hooray | | rocket | rocket | | eyes | eyes |

Configuration

All options are auto-detected from environment variables when not provided.

| Option | Required | Description | |--------|----------|-------------| | token | No* | Personal Access Token. Auto-detected from GITEA_TOKEN | | baseUrl | Yes | Gitea instance URL. Auto-detected from GITEA_BASE_URL | | webhookSecret | Yes | Webhook secret. Auto-detected from GITEA_WEBHOOK_SECRET | | userName | No | Bot username for @mention detection. Auto-detected from GITEA_BOT_USERNAME (default: "gitea-bot") | | botUserId | No | Bot's numeric user ID (auto-detected if not provided) | | logger | No | Logger instance (defaults to ConsoleLogger("info")) |

*token is required either via config or GITEA_TOKEN env var.

Environment variables

GITEA_TOKEN=your-personal-access-token
GITEA_BASE_URL=https://gitea.example.com
GITEA_WEBHOOK_SECRET=your-webhook-secret
GITEA_BOT_USERNAME=my-bot         # Optional

Features

Messaging

| Feature | Supported | |---------|-----------| | Post message | Yes | | Edit message | Yes | | Delete message | Yes | | File uploads | No | | Streaming | Accumulate + post |

Rich content

| Feature | Supported | |---------|-----------| | Card format | GFM Markdown | | Buttons | No | | Link buttons | No | | Select menus | No | | Tables | GFM | | Fields | Yes | | Images in cards | Yes | | Modals | No |

Conversations

| Feature | Supported | |---------|-----------| | Slash commands | No | | Mentions | Yes | | Add reactions | Yes | | Remove reactions | Yes | | Typing indicator | No | | DMs | No | | Ephemeral messages | No |

Message history

| Feature | Supported | |---------|-----------| | Fetch messages | Yes | | Fetch thread info | Yes | | List threads | Yes | | Fetch channel info | Yes | | Post channel message | No |

Limitations

• No typing indicators — Gitea does not support typing indicators
• No real-time streaming — Messages are accumulated and posted in full
• No DMs — Gitea does not have direct messages
• No modals — Gitea does not support interactive modals
• Action buttons — Rendered as text; use link buttons for clickable actions

Troubleshooting

"Invalid signature" error

• Verify GITEA_WEBHOOK_SECRET matches your webhook configuration
• Ensure the request body is not modified before verification

"Invalid JSON" error

• Change webhook Content Type to application/json

Bot not responding to mentions

• Verify webhook events are configured (Issue Comments, Pull Request Review Comments)
• Check the webhook URL is correct and accessible
• Ensure the userName config matches the bot's Gitea username

License

MIT