Getting data in, and keeping it in sync

Organisation, then tenant, then platform

Outbound configuration resolves down a three-level ladder — organisation → tenant → platform — and the lowest appropriate configuration wins. A tenant can set a house default that an individual organisation overrides for its own branding, without either of them having to know the platform settings.

Every secret is encrypted per field: SMTP password, API key, OAuth client secret and tokens. There is a connection test and a test send at every level, plus a view showing which configuration is actually in effect — the question that otherwise takes an afternoon to answer.

Twelve settings that make a mailbox behave

Name, address, provider, enabled flag, JSON configuration, poll interval (five minutes by default), whether to store the original .eml, whether to extract attachments, the reply-handling mode, and default ticket type, priority and assignee. Plus last poll, last error and an error count.

A mailbox is scoped to an organisation or to a single project. OAuth uses a three-legged flow with a provider-and-connection mismatch guard, per-organisation client credentials held encrypted, and pre-expiry token refresh — so the mailbox does not go quiet at 3am because a token lapsed.

Three modes, and retired keys still resolve

ALWAYS_NEW_TICKET creates a ticket every time. MATCH_BY_SUBJECT finds a ticket key with a regex, resolved only within that mailbox's own organisation — and including retired project keys, so a thread that started before a project was re-keyed still lands on the right ticket. MATCH_BY_THREAD uses the thread id, In-Reply-To and References.

Processing is deduped by message id, then creates a ticket or appends a comment, finds or creates a customer account from the sender, initialises SLA on new tickets, adds the customer as a watcher and sends the confirmation after commit.

The auto-responder loop, closed

An auto-response detector skips out-of-office replies, bounces and DSNs, mailing-list confirmations and other automation. Without it, a support queue and a vacation responder will happily talk to each other all weekend.

A reply parser strips quoted chains: >-prefixed quoting, Outlook's -----Original Message-----, the Gmail and Apple Mail "On [date], [name] wrote:" form, Thunderbird, and forwarded blocks. Customers reply on top of the whole thread; the ticket should not accumulate it.

Three, and each of them is a migration story

INBOUND makes the remote the source of truth — the shape you want while migrating onto Trakr, with the forge still authoritative. OUTBOUND makes Trakr the source of truth, which is what you switch to when migrating off a forge. BOTH is a true mirror, and the default.

The three directions are one setting, so a migration is a change of direction rather than a rebuild of the integration.

Comments, labels and state toggle independently

Each of the three can be turned on or off on its own. Open-status and closed-status mapping is configurable, there is a default ticket type for issues arriving from the remote, and mirrored writes are attributed to an account you nominate.

Label mapping works by name, case-insensitively, creating labels on demand on either side. Explicit rows handle names that genuinely differ — kind/bug against bug — and mapping a remote label to an empty local name blocks it from crossing at all, which is how you keep a forge's internal triage labels out of your tracker.

Five ways a sync starts

POLL on a per-mirror interval, fifteen minutes by default, cursor-based so the remote is asked only for what changed. WEBHOOK on issues and issue_comment events, HMAC-verified, with GitLab's token header supported. MANUAL for a "sync now". IMPORT for a full backfill that adopts existing issues.

And TICKET_EVENT, a Trakr-side change pushed outward — dispatched after commit and executed asynchronously, so a slow or unreachable forge never slows down a user's save and never rolls one back.

The problem every two-way mirror has

Write to the remote, the remote fires a webhook, the webhook writes back locally, which fires an outbound sync. Left alone, this runs forever.

Trakr breaks it in two different ways because issues and comments have different shapes. Issues carry a lastSyncedHash over the local field set — summary, description, open or closed, label names — so an echo that changes nothing meaningful is dropped. Comments, being append-only, use per-comment origin link rows instead: a comment that came from the remote is known to have come from the remote.

HTML and Markdown, converted both ways

Outbound, sanitised HTML becomes Markdown: headings, paragraphs, emphasis, lists, links, images, code, quotes and tables, with anything else degrading gracefully to text. Inbound, Markdown becomes HTML and is then re-sanitised.

Because the mirror writes with a single bot token, every mirrored item carries a fenced trakr:meta block naming the real author and the ticket key and URL. Otherwise a year of migrated discussion ends up attributed to a service account.

Monorepo split, and short transactions

A single repository can be mirrored by several projects at once — the monorepo split — with each project verifying its own webhook secret. One repo, several trackers, no shared secret.

Each issue gets one short transaction rather than one long transaction per run, paging is capped at 40 × 100, and run history — status, trigger, issues pulled and pushed, comments pulled and pushed, skipped count, error, who ran it and timings — is kept for thirty days and pruned nightly. The mirror token is deliberately separate from the coding token: it only needs issues scope. Disconnecting a mirror keeps everything.

Move to a tenant, merge, or split

Three operations: MOVE_TO_TENANT, MERGE and SPLIT. Between them they cover the acquisition, the consolidation and the demerger — the three events that otherwise turn a tracker into an archive nobody can use.

A preview that writes nothing

Every restructuring starts as a dry-run preview. It computes the whole plan — what moves, what is reused, what collides — and writes nothing. Only then do you apply.

People are handled per user with an explicit decision: MOVE, STAY or LINK. Nobody is moved by inference.

Matched config is reused, the rest is cloned

Configuration matched by name is reused at the destination and everything else is cloned, with ticket pointers — statuses, types, priorities, incident flags — re-pointed to the objects that now apply.

Collisions are detected and resolved in place rather than aborting the whole operation and leaving you to guess which of four hundred names was the problem.

Every retired key still resolves

Projects are re-keyed where they must be, with a free-key suggestion offered. Crucially, every retired key is preserved, so old links keep working — and email threads keep matching, because MATCH_BY_SUBJECT resolves retired keys too.

The whole operation is audited: the operation itself, its status, source and target, the plan JSON, the result JSON, any error, and the actor. A failure is written in its own transaction, so the record of what went wrong survives the rollback of what went wrong.