Pre-Merge Check
A conflict you find after merging is a conflict someone has to come back to. The pre-merge check moves that moment earlier: it runs on the pull request and reports what the sync would do with the change, as a GitHub check named Meldoc: <project-alias>.
Problems are reported as annotations at the file and line they are in, so the author reads them where they are looking rather than in a summary at the bottom of a thread.
It is off by default and switched on per project, in the project’s Repositories panel. Project administrators only.
What it reports
| Result | When |
|---|---|
| Success | The merge is clean, or the pull request touches no document of this project |
| Failure | A conflict the merge cannot decide, or front matter that does not parse |
| Neutral | It could not answer — usually meldoc.config.yml missing or unreadable |
A link or image the repository does not have is a warning, not a failure. The real import accepts such a document and warns, and a check stricter than the merge it predicts would block changes that would have been fine.
Nothing is written while the check runs. No document, no conflict, no uploaded image. A pull request that never merges leaves no trace.
What it looks at, and what it cannot
A green check that had not looked at something is worse than no check, so the summary always states both columns.
Checked: that meldoc.config.yml parses, which files are in scope, how aliases come out, the document scan and its front matter, the three-way merge, and whether file and image links resolve.
Not checked: anything only the actual write can know — whether an alias collides with a document that already exists, an unknown template, permission refusals, where a document lands in the tree, and custom fields.
Making it required
The check’s name never changes, so you can mark it required in the repository’s branch protection rules. Two things follow, and both are yours to weigh:
- A pull request that touches no documentation still gets the check, as a green Nothing to check. Without that, a required check would never report on such a pull request and it would wait for a status for ever.
- Turning the check off stops it being posted at all. If it is required, open pull requests then cannot merge until you change the rule in GitHub — Meldoc cannot read or edit branch protection. The web warns you and asks for confirmation before switching it off.
What it skips
Pull requests from a fork get no check: the app’s access does not reach the fork.
A repository feeding several projects gets one check per project, because the switch is per project.
Check runs do not appear in the ordinary run list, and they never hold up a real sync.
What’s next?
Resolve a Conflict — Resolving one that got through anyway.
Documentation Review — The other check: what this pull request makes untrue.
CI/CD Integration — Running the CLI in your own pipeline instead.