For developers · Privacy and data
Chat notification
Gitoodo can report new questions to a chat through an outgoing webhook (Slack, Teams, or Matrix/generic). It is off by default. Settings: type, webhook URL, on/off, "send question text", "daily digest", the login-to-handle mapping for mentions, and "send test message".
Secret handling#
- The webhook URL is a secret. It lives only in the keychain (service
gitoodo, keychat-webhook), never in the settings file, an export, a log line or an error text. - The frontend can only ask "configured yes/no"; the URL is write-only.
- Failures are reported as a category (
invalid,not_configured,unreachable,timeout,tls,status,keychain) and logged with the host only. - All network access is in
crates/core/src/chat.
Message#
Repo, title, deadline and a link to the issue. The question text is added only with the option "send question text" (default off) and is cut at 500 characters. Payload per type:
| Type | Body |
|---|---|
| Slack | {"text": ...} (mrkdwn) |
| Teams | message with one Adaptive Card 1.4 attachment |
| Matrix / generic | {"text": ..., "html": ...} (plain text and escaped HTML, for hooks) |
Mentions#
A message mentions the person asked: the login in the header of the question's first addressed
block, or the new person of a forward. The settings map forge logins to chat handles; the mapping
is not a secret and lives in the settings file (chat.handles). Logins match in any case. A login
without a usable handle gets no mention. A handle must not contain blanks, control characters or
< > & " |, and is at most 128 characters; at most 200 mappings are kept.
| Type | Handle | Written as |
|---|---|---|
| Slack | member ID U…/W…, user group ID S… | <@U…>, <!subteam^S…>; anything else as plain @handle |
| Teams | sign-in address (UPN) or Entra object ID | <at>handle</at> plus a mention entity in msteams |
| Matrix | user ID @user:server | link pill to https://matrix.to/#/@user:server; else text |
Forwards#
Forwarding a question (see docs/question-format.md, "Forwarding") sends one message "Question
forwarded: <title>" with repo, link and the mention of the new person, never the question text.
It counts against the same hourly limit; in digest mode it becomes a digest line.
Daily digest#
With "daily digest" (default off) new questions are not sent one by one. They are queued in
chat-notified.json and sent as one message once a day has passed since the first queued item:
a title with the count, then one line per question with title, repo, link and mention (at most 20
lines, then "+N"). The digest never carries the question text. The queue survives a restart; the
rules below (once per question, no replay, hourly limit) still apply.
Delivery rules#
- At most once per question: a question is marked as reported before it is sent and the mark is
persisted (
chat-notified.json), so a restart never repeats it. A failed send is not repeated. - No replay: a question waiting longer than 1 hour is marked as reported without sending. This covers offline gaps, the first poll after a restart and the moment the feature is enabled. Such questions are dropped, not caught up.
- Bursts: per poll at most 3 single messages; the rest is one summary message ("N more questions").
- Rate limit: at most 20 messages per hour, 1 s between messages; the excess is dropped and logged.
- Errors: exactly one attempt, no retry. After a failure the rest of that batch is dropped. The warning is throttled.
- Removing an account forgets its marks and its queued digest lines.