Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · Privacy and data

Chat notification

On this page
  1. Secret handling
  2. Message
  3. Mentions
  4. Forwards
  5. Daily digest
  6. Delivery rules

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, key chat-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:

TypeBody
Slack{"text": ...} (mrkdwn)
Teamsmessage 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.

TypeHandleWritten as
Slackmember ID U…/W…, user group ID S…<@U…>, <!subteam^S…>; anything else as plain @handle
Teamssign-in address (UPN) or Entra object ID<at>handle</at> plus a mention entity in msteams
Matrixuser ID @user:serverlink 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#

  1. 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.
  2. 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.
  3. Bursts: per poll at most 3 single messages; the rest is one summary message ("N more questions").
  4. Rate limit: at most 20 messages per hour, 1 s between messages; the excess is dropped and logged.
  5. Errors: exactly one attempt, no retry. After a failure the rest of that batch is dropped. The warning is throttled.
  6. Removing an account forgets its marks and its queued digest lines.
Docs version: dev