Integrations internals
How connections are stored, how write-back and Linear’s comments run, and how the one-time tracker import works, for people changing that code. The user guides are Integrations and Import from a tracker.
Connections
integrations holds the workspace’s connections (is_default, name; secret_name is the Vault entry the token is
kept under, or the server’s keyring). team_connections holds each team’s pick, with a mapping of
key_prefixes and writeback that overrides the connection’s. private.integration_for resolves a team’s connection
(its own pick, a parent’s, else the default) and private.integration_config_for its settings, so imports, link
resolving and write-back all follow the pick. Migration 20261110064100_workspace_connections.
Tokens go through integration-secrets, which checks each with the provider before keeping it and never returns it.
The write-back switches are each provider’s events in apps/board/src/lib/integrations.ts.
Asana sign-in
Connect with Asana sends the browser to Asana’s consent page with a state signed for this org and person with
the client secret (valid 10 minutes). Asana returns to /settings/integrations/asana?code=…&state=…, and the page
passes both to integration-secrets (oauth_finish), which checks the state, swaps the code for an access and a
refresh token, and keeps them together; config.auth records pat or oauth. asanaToken
(apps/server/src/functions/shared/asana.ts) refreshes an OAuth token within five minutes of expiry; a refused refresh sets
the connection’s last_error. Rotating the client secret only restarts consents in flight.
The app’s scopes, when it uses granular ones, must cover what the import, the sync and write-back do: users, workspaces, teams, projects and tasks read, stories and attachments read, webhooks create and delete, and tasks and stories write.
Write-back
Asana write-back runs in apps/server/src/functions/shared/asana-writeback.ts, through links-writeback. Each attempt is a
writeback event on the card’s latest run and stays on its outbox row for a week. The outbox has no client access;
the Sync health panel calls tracker-import {action: 'asana_health'}, which checks the caller’s role, then reads the outbox and the import list.
Linear comments
import_issue_comments (service role only, migration 20261112143225_linear_comments) copies up to 500 comments when a
card is made from an issue, keyed by <issue id>/<comment id> in card_comments.external_ref, so a second import adds
no copies. Comments the write-back posted are skipped. In a run’s {{comments}} they are marked from Linear.
The tracker import
The tracker-import function (/api/fn/tracker-import and the tracker-import job) runs
apps/server/src/functions/shared/tracker-import-job.ts.
- Readers and the dry run are pure:
packages/shared/src/tracker-parse.tsandtracker-import.ts, which the job imports from@andon/shared.parseTrelloreads both Trello’s export and its API pages;parseAsanareads Asana’s REST pages. - Slices. The job works in slices with a lease (
import_job_claim) and queues the next itself (import_job_kick→private.call_function). Where the database can’t call functions, the open Settings page drives it. - Writes:
import_job_prepare(team, statuses, projects, cycles, milestones, fields, former members),import_job_card(a card with its comments and links),import_job_relations,import_job_templatesandimport_job_apply_templates,import_job_finish. - Idempotence. A card is found again by
card_links (org, provider, external_id); a comment, status, cycle or field byprivate.import_refs; a project or milestone by its tracker id; a file bycard_attachments.source_ref. - Rate limits. One request at a time per tracker: Trello 120 ms apart, Asana 400 ms. A 429 waits as asked, up to a minute.
- Trello’s API. The key and token are one secret (
<key>:<token>,apps/server/src/functions/shared/trello.ts), sent in theAuthorization: OAuth …header, never a URL. The board is read in the export’s shape, then the comment and create actions are paged past the first 1,000. - Asana reading (
apps/server/src/functions/shared/asana-import.ts,asanaReadSlice): workspace, team, users and projects; each project’s sections and task pages (100 a page); subtasks at any depth; then each task’s stories and attachments. The bundle grows in the job until it’s all read. A file’s signeddownload_urlis fetched fresh (GET /attachments/{gid}) when it is copied, and the token never goes with the download. - Asana sync. Each synced project is an
asana_webhooksrow. The handshake’sX-Hook-Secretis kept like a token and answered only for a subscription made in the last ten minutes. A delivery must carry a validX-Hook-Signature(HMAC-SHA256 of the body) or gets 401; an unknown subscription gets 410. Deliveries queue task ids (asana_sync_enqueue);asana_sync_kickrunstracker-import {action: 'sync'}, which rereads them in batches.asana_sync_claimkeeps a sync and a re-run apart. Deliveries arrive atasana-webhook(/functions/v1/asana-webhookon the server). - Former members.
former_membersrows;cards.former_assignee_idandcard_comments.former_author_idpoint at them. The email is inprivate.former_member_emails.invite_former_membercallscreate_invitefrom the private address, andlink_former_membersetsformer_members.user_id. Migration20261108192317_tracker_import.
Not covered yet
fixtures/asana/move-team.jsonandfixtures/trello/board-export.jsonare built from the providers’ API references, not captured from real workspaces.- A Jira XML export’s components and affected versions aren’t read.
