Sync with GitHub
GitHub sync makes each issue and pull request in a repo a thread in a board channel, its comments and reviews replies, and its state labels on the root. What’s written on the board in those threads goes back to GitHub as comments, posted with the token you give it.
import { defineWorkbus, githubProvider, type Secret } from 'workbus'import type { GatewayEnv } from 'workbus/gateway/gateway.ts'
type Env = GatewayEnv & { MAILBOX: DurableObjectNamespace; GITHUB_WEBHOOK_SECRET: Secret; GITHUB_TOKEN: Secret }
export const { Ledger, Relay, Mailbox, Inbox, Workbus, BoardSession, gateway } = defineWorkbus<Env>((env) => ({ sync: { // Issues and pull requests in acme/web become threads in github/web. github: githubProvider({ webhookSecret: env.GITHUB_WEBHOOK_SECRET, repos: { 'acme/web': 'github/web' }, token: env.GITHUB_TOKEN }), },}))
export default { fetch: (request: Request, env: Env) => gateway(request, env) }An issue opened, a comment, a reply from the board, and the issue closed:
$ wb read 8#8 ada 2026-11-20 15:20 **Issue #7: Checkout button does nothing on Safari**
Clicking it logs a TypeError. labels issue=acme/web#7, state=closed
#10 jared 2026-11-20 15:21 Reproduced on Safari 19; fix incoming
#13 bo 2026-11-20 15:21 Still broken on 19.1Set it up
Section titled “Set it up”-
Deploy a board with the sync. The sync’s key (
githubabove) names its webhook route and prefixes its users and threads. The deployment needs theINBOXandMAILBOXbindings (Deploy and operate). -
Give it its secrets. The webhook secret is any long random string; the token is one that may comment on the repo’s issues and pull requests.
Terminal window npx wrangler secret put GITHUB_WEBHOOK_SECRETnpx wrangler secret put GITHUB_TOKENEither can be a Secrets Store binding instead.
-
Point GitHub’s webhook at the board. On the repo (or your GitHub App), add a webhook:
Setting Value Payload URL https://<your board's origin>/b/<board>/webhooks/githubContent type application/jsonSecret the GITHUB_WEBHOOK_SECRETvalueEvents Issues, Issue comments, Pull requests, Pull request reviews, Pull request review comments, and Pushes for Markdown docs GitHub’s ping answers
pong. A delivery signed with any other secret answers 401:200 kept 1401 not signed by this app
What comes in
Section titled “What comes in”| On GitHub | On the board |
|---|---|
| an issue opened | a thread: **Issue #7: <title>** and its body, labels issue=acme/web#7, state=open |
| a pull request opened | a thread with its link, labels pr=acme/web#12, state=open or draft |
| closed, reopened, merged, drafted | the root’s state: closed, not-planned, merged, open, draft |
| a comment, or a review comment | a reply; a review comment starts with its path:line |
| a review | a reply (**Review: approved**), and review=approved or changes-requested on the root |
| an edit or a delete | the board message edited or deleted |
Each message is written by its GitHub author, github:user:<id>, with from: "github" and an origin naming the GitHub thread. Repos you didn’t map are ignored. starts decides which events may start a thread: the factory uses it to skip forks’ pull requests and its own app’s.
$ wb tail github/web15:20:59 message.posted #8 github/web ada **Issue #7: Checkout button do...15:21:07 message.posted #10 github/web jared re #8 Reproduced on Safari...15:21:23 message.posted #13 github/web bo re #8 Still broken on 19.115:21:23 labels.changed #8 github/web ada state=closedWhat goes back
Section titled “What goes back”A message written on the board in a synced thread is posted to GitHub as a comment with the provider’s token; editing it edits the comment, deleting it deletes it, and a reaction GitHub has (+1, eyes, rocket, heart, and the rest) is added to it. A board thread you send to a repo ("sync": ["github:acme/web"] on the post) opens an issue, its first line the title. Labels aren’t copied, a removed reaction isn’t, and a person’s reply is posted as the token’s user without naming its author.
token is one token for every repo (a Worker secret or a Secrets Store binding), or a function of the repo that answers one, such as a GitHub App’s installation token:
// in githubProvider's options: an installation token for the thread's repo, from your own codetoken: async (repo) => installationToken(env, repo),// the app's bot user ID: its own comments come back as GitHub's echo, and aren't imported againbotUserId: env.GITHUB_BOT_USER_ID,With botUserId, the app’s own comments wait for the courier’s receipt, and land on the board as nothing: the board already has them.
When a copy fails
Section titled “When a copy fails”The courier retries a comment until it lands, and the receipt it records is the guard: a copy that exists is never posted again. A refusal that won’t change (a 4xx that isn’t a rate limit) is recorded at once. Here the token was wrong:
#10 jared 2026-11-20 15:21 Reproduced on Safari 19; fix incoming undelivered github:acme/web:7 GitHub answered 401 to POST /issues/7/comments: { "message": "Bad credentials", "documentation_url": "https://docs.github.com/rest", "status": "401" }15:21:07 message.sync_failed #10 github/web - github:acme/web:7 GitHub...GET /messages/:id/sync says where a thread syncs and where each copy is:
{"targets":[{"target":"github:acme/web:7","key":"github","thread":"github:acme/web:7","message":"issue","url":null,"undelivered":null}]}Markdown docs
Section titled “Markdown docs”With docs, the Markdown files under a directory of a repo are docs on the board, both ways. docs/runbooks/deploy.md in acme/web is the doc docs/web/runbooks/deploy:
// in githubProvider's optionsdocs: { 'acme/web': { dir: 'docs', channel: 'docs/web' } }, // on the repo's default branch; branch: '<name>' for anotherbotUserId: env.GITHUB_BOT_USER_ID, // the app's own pushes aren't importedThe webhook needs Pushes too, and the token needs to write the repo’s contents (a GitHub App’s Contents: read and write). These transcripts are from a local run of the provider with a stand-in for GitHub’s API; the board side is as it answered.
A push imports each changed file. A push to the branch imports every Markdown file under dir that it added or changed, as a whole-body merge against the file as it was before the push (base). What was written on the board since stays; a new file makes a new doc:
$ wb docs docs/docs/web/runbooks/deploy revision 2 2026-11-20 19:24 Deploy$ wb doc read docs/web/runbooks/deploy --outlinedocs/web/runbooks/deploy revision 2 Deploy
ship Ship changed 2 ship/rollback Rollback changed 2 monitoring Monitoring changed 2A board write commits as the app. A doc made, edited, or moved on the board is written to its file by the sync’s courier, with the token, as a commit like docs: update docs/runbooks/deploy.md from the board (revision 7, workbus:user:jared). A file that already says what the doc says gets no commit, which is the retry guard. A doc made under the channel gets its file (docs: add docs/onboarding.md from the board):
$ wb doc edit docs/web/runbooks/deploy --section monitoring --revision 2 'Watch the error rate and p95 latency for an hour.'edited docs/web/runbooks/deploy revision 7$ printf '## First day\n\nGet access to the repo and the board.\n' | wb doc create docs/web/onboarding -made docs/web/onboarding #14 revision 14
first-day First day changed 14Edits on both sides converge. A board edit to one section and a push that changed another, at the same moment, both land: the push merges into the doc by section, and the merged doc is committed back, so the file and the doc end up the same.
A conflict makes a task. When a push and the board changed the same section, the board keeps its version, and a task in the doc’s channel links the file as the push left it:
$ wb doc edit docs/web/runbooks/deploy --section ship/rollback --revision 9 'Roll back with deploy rollback <id>, the ID of the last green version.'edited docs/web/runbooks/deploy revision 10$ wb tasks docs/web/ --state all#11 docs/web/runbooks ready github-sync acme/web/docs/runbooks/deploy.md...$ wb read 11#11 github-sync 2026-11-20 19:24 acme/web/docs/runbooks/deploy.md and [[docs/web/runbooks/deploy]] both changed `ship/rollback`. The board kept its version; the other is at https://github.com/acme/web/blob/6c1ed3abffa16133d4e04d59a72a9f78f6bb8636/docs/runbooks/deploy.md. Fold them together in the doc, then complete this task. task ready$ wb doc read docs/web/runbooks/deploy --section ship/rollbackRoll back with deploy rollback <id>, the ID of the last green version.The doc’s history says which edits came from the repo:
$ wb doc history docs/web/runbooks/deploy2 2026-11-20 19:24 workbus:sync:github created7 2026-11-20 19:24 workbus:user:jared edited monitoring8 2026-11-20 19:24 workbus:sync:github edited ship/rollback9 2026-11-20 19:24 workbus:user:jared edited ship10 2026-11-20 19:24 workbus:user:jared edited ship/rollbackA move deletes the old file. Moving a doc commits its file at the new path and deletes the old one (docs: move docs/runbooks/deploy.md to docs/ops/deploy.md (from the board)):
$ wb doc move docs/web/runbooks/deploy docs/web/ops/deploymoved to docs/web/ops/deployA few things stay on one side:
- The app’s own pushes (by
botUserId) aren’t imported: the board has them already. - A file deleted in the repo leaves its doc on the board. Deleting a doc is a person’s call.
- A file whose path can’t be a doc (an uppercase letter, a space) is left out, with a line in the Worker’s logs. A path segment is a channel segment, and the file name a slug.
- A doc’s comments stay on the board: its thread syncs as the doc, not as messages.
Projects
Section titled “Projects”An organization’s GitHub Projects ride on the same sync: with projects and orgToken, a Project item is its issue’s thread (or a thread in the Project’s channel), its fields are labels on that thread, and a Status mapping makes a card moved to a column a ready task. Sync with GitHub Projects has the setup and the rules.
How it works
Section titled “How it works”GitHub’s webhook goes to the sync’s Inbox, a Durable Object of its own, which keeps each delivery under GitHub’s delivery ID before GitHub hears 200, so a redelivery does nothing. The Inbox imports events one GitHub thread at a time, oldest first, with 5 tries each; a failed one can be replayed. On the way out, the courier is a Mailbox that the board feeds every write in a synced thread, in the thread’s order. Sync: Inbox and courier has the details, and the webhooks reference what each route verifies.