The repository and the board, telling the same story

It is three layers, and keeping them separate is what stops one careless click rewiring an organisation. An administrator makes one connection per organisation, using either a GitHub App or a personal access token. Somebody who may manage boards then links a board to a repository, a Projects v2 project, or both. From there each card carries its own reference to the issue, pull request or project item it stands for.

• One connection per organisation, made by an administrator
• One link per board, guarded by the permission that already governs boards
• One reference per card, guarded by the permission that already governs cards
• GitHub Enterprise Server is supported by storing its API host and its web host separately
• Credentials are encrypted with AES-256-GCM before they are stored, never held in the clear

Issues and pull requests arrive as board items. Board columns map onto the Status field of a GitHub Projects v2 project, so moving a card and moving a project item mean the same thing. Each card caches what it points at — the state, the review decision and the check rollup — so a reviewer can see that the build is red without opening another tab.

• Issues in, cards out, kept in step as either side changes
• A pull request that closes an issue attaches to that issue’s card
• Column to Projects v2 Status field mapping, set once per board
• Check rollup and review decision cached on the card
• A card can be filed as a new GitHub issue from Enclessa

A setting called “write changes back to GitHub”, which an organisation controls. When it is off, a link that would push a moved card to GitHub stops writing and carries on reading. It is the first module setting the platform actually reads at runtime, and it exists because a connector that silently starts editing a repository because somebody tidied a board is a connector nobody keeps.

• Write-back is a per-organisation setting, not a per-user habit
• With it off, the connector is read-only and says so
• Every inbound delivery is signature-verified before it is acted on
• Deliveries are recorded before they are applied, and a replayed delivery id is a no-op
• The console shows a delivery log, so a missing update is diagnosable

A closed set of six, chosen rather than accumulated: issues, issue comments, pull requests, pull-request reviews, Projects v2 item changes and check suites. Anything else that arrives is recorded as ignored rather than half-handled. Deliveries are applied one at a time per installation, because GitHub’s secondary rate limits punish concurrency from a single installation harder than they punish volume.

• issues, issue_comment, pull_request, pull_request_review, projects_v2_item, check_suite
• Unrecognised events are recorded as ignored, not guessed at
• Applied strictly in order per installation, to stay inside GitHub’s rate limits
• Recorded deliveries are pruned after a week