How to sync Markdown reviews with your GitHub repo

You can keep a Markdown review in two-way sync with a GitHub repo: pushes to a watched branch become new versions in Seal, PR comments flow into the review, and accepted suggestions go back as PR suggested changes. The point is to let non-developers review a doc that lives in a repo without ever touching the repo. You install the sealmd-app GitHub App once, pick the file at /new, and the review stays tied to the source of truth in git. Here’s the setup and what each direction of the sync does.

How do I connect a GitHub repo to a Markdown review?

Two steps. First, install the sealmd-app GitHub App on the repos you want Seal to see — click Connect with GitHub on /new, or install directly from github.com/apps/sealmd-app. It’s a normal GitHub App install, scoped to the repos you choose. Second, go to /new on the hosted product and, instead of uploading a .md file, pick a file from GitHub: repo → branch → file. Seal imports that file as the first version of the review, and reviewers can start commenting on the rendered document immediately.

What syncs from GitHub into Seal?

Two inbound streams. When anyone pushes to the watched branch, a webhook fires and Seal ingests the change as a new version — merged with a 3-way merge, with each reviewer’s role-tailored AI summary regenerating so they see what changed from their angle. And once a pull request is tied to the review — Seal opens one against the watched branch when you take the PR write-back path below — comments on that pull request sync into Seal too, so a developer leaving feedback in the GitHub PR and a legal reviewer commenting in the browser end up in the same thread of record, not two.

The workflow, step by step

Install the sealmd-app GitHub App. Click "Connect with GitHub" on /new — or install directly at github.com/apps/sealmd-app — and grant the App the repos you want to sync.
Pick a repo, branch, and Markdown file at /new. Instead of uploading a .md file, choose a file from GitHub: repo → branch → file. That import is the first version of the review.
Push to the watched branch to publish new versions. Every push triggers a webhook and lands as a new version in Seal, with each reviewer’s role-tailored summary regenerated.
Choose how accepted suggestions write back. The first time an accepted suggestion needs the repo, Seal prompts you once: PR suggested changes (the default — Seal opens a pull request against the watched branch) or a direct commit. Your authored Markdown style is preserved on push.
Let PR comments flow into the review. Comments on that Seal-opened pull request sync inbound, so GitHub-side and browser-side feedback land in one place.

How do accepted suggestions get back into the repo?

Write-back is a per-user choice, and Seal prompts you exactly once. The default is PR suggested changes: Seal opens a pull request against the watched branch, and accepted suggestions appear on it as GitHub suggestions, so a human still merges them in GitHub’s own UI — and that same pull request is where inbound comments sync from. If you prefer, you can choose a direct commit to the branch instead. Either way, your authored Markdown style is preserved on push — Seal isn’t a Markdown editor; it’s the review layer, and it doesn’t reformat your source.

Does Seal write to my repo without asking?

No. Write-back is opt-in and per-user: Seal asks you once, the first time an accepted suggestion needs to reach the repo, and nothing is pushed before you answer. The two paths — PR suggested changes or a direct commit — are covered in the write-back section above.

What happens on conflicting edits?

They meet in one version instead of racing. A push arriving while review activity is pending in Seal doesn’t replace it: the 3-way merge reconciles both sides into a single new version, and role summaries regenerate against that merged result — so no reviewer is left looking at a copy the repo has already moved past.

Do reviewers need GitHub accounts?

No — that’s the reason hosted GitHub sync exists. Reviewers open the review page in any browser, read a summary written for their role, and comment or suggest changes with no GitHub account, no repo access, and no git knowledge. Reviewers never consume a paid seat on any tier, and only the outcomes they drive — accepted suggestions — travel back to the repo, through the GitHub App path you opted into.

How is this different from the local sealmd plugin?

The free, open-source local plugin is git-native by itself: review state lives in a doc.seal.md sidecar committed next to your document, git is the transport, and no GitHub App is needed at all — sign-off there is a normal GitHub PR. Hosted GitHub sync is for the other half of the audience: reviewers who will never clone the repo but whose feedback still needs to land in it. If everyone on the review can already pull the repo, start with the plugin (set up the sealmd plugin); if they can’t, connect the repo as above (getting started with hosted Seal).

Connect a repo at /new →Get the free local plugin