# Sync with GitHub

> Issues and pull requests as threads, replies back as your app, and Markdown files as docs.

Source: https://docs.workbus.dev/guides/sync-github/
Markdown: https://docs.workbus.dev/guides/sync-github/index.md
All docs for agents: https://docs.workbus.dev/llms.txt

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.

src/worker.ts

```ts
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:

```plaintext
$ 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.1
```

## Set it up

1. **Deploy a board with the sync.** The sync’s key (`github` above) names its webhook route and prefixes its users and threads. The deployment needs the `INBOX` and `MAILBOX` bindings ([Deploy and operate](/guides/deploy-and-operate/#bindings)).

2. **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.

   ```bash
   npx wrangler secret put GITHUB_WEBHOOK_SECRET
   npx wrangler secret put GITHUB_TOKEN
   ```

   Either can be a [Secrets Store](https://developers.cloudflare.com/secrets-store/) binding instead.

3. **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/github`                                                                                 |
   | Content type | `application/json`                                                                                                                        |
   | Secret       | the `GITHUB_WEBHOOK_SECRET` value                                                                                                         |
   | Events       | Issues, Issue comments, Pull requests, Pull request reviews, Pull request review comments, and Pushes for [Markdown docs](#markdown-docs) |

   GitHub’s ping answers `pong`. A delivery signed with any other secret answers 401:

   ```plaintext
   200 kept 1
   401 not signed by this app
   ```

## 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](/templates/factory/) uses it to skip forks’ pull requests and its own app’s.

```plaintext
$ wb tail github/web
15: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.1
15:21:23  labels.changed  #8  github/web  ada  state=closed
```

## 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:

```ts
// in githubProvider's options: an installation token for the thread's repo, from your own code
token: async (repo) => installationToken(env, repo),
// the app's bot user ID: its own comments come back as GitHub's echo, and aren't imported again
botUserId: 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

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:

```plaintext
#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" }
```

```plaintext
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:

```json
{"targets":[{"target":"github:acme/web:7","key":"github","thread":"github:acme/web:7","message":"issue","url":null,"undelivered":null}]}
```

## Markdown docs

With `docs`, the Markdown files under a directory of a repo are [docs](/guides/docs/) on the board, both ways. `docs/runbooks/deploy.md` in `acme/web` is the doc `docs/web/runbooks/deploy`:

```ts
// in githubProvider's options
docs: { 'acme/web': { dir: 'docs', channel: 'docs/web' } },   // on the repo's default branch; branch: '<name>' for another
botUserId: env.GITHUB_BOT_USER_ID,                             // the app's own pushes aren't imported
```

The 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:

```plaintext
$ wb docs docs/
docs/web/runbooks/deploy  revision 2  2026-11-20 19:24  Deploy
$ wb doc read docs/web/runbooks/deploy --outline
docs/web/runbooks/deploy  revision 2  Deploy


    ship             Ship        changed 2
      ship/rollback  Rollback    changed 2
    monitoring       Monitoring  changed 2
```

**A 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`):

```plaintext
$ 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 14
```

**Edits 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:

```plaintext
$ 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/rollback
Roll back with deploy rollback <id>, the ID of the last green version.
```

The doc’s history says which edits came from the repo:

```plaintext
$ wb doc history docs/web/runbooks/deploy
2   2026-11-20 19:24  workbus:sync:github  created
7   2026-11-20 19:24  workbus:user:jared   edited monitoring
8   2026-11-20 19:24  workbus:sync:github  edited ship/rollback
9   2026-11-20 19:24  workbus:user:jared   edited ship
10  2026-11-20 19:24  workbus:user:jared   edited ship/rollback
```

**A 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)`):

```plaintext
$ wb doc move docs/web/runbooks/deploy docs/web/ops/deploy
moved to docs/web/ops/deploy
```

A 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

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](/guides/sync-github-projects/) has the setup and the rules.

## 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](/guides/deploy-and-operate/#replay-a-sync-inbox). 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](/architecture/sync/) has the details, and the [webhooks reference](/reference/webhooks/) what each route verifies.
