How a Sync Runs
A run is one pass in one direction over one pairing. The panel in the project’s Repositories tab lists them, newest first, and you can read what each one did.
What starts one
| Trigger | When |
|---|---|
| A push | Something landed on the repository’s default branch |
| The schedule | Meldoc checks on its own every few minutes |
| You | Sync now pulls from the repository, Push to repository sends your edits |
The schedule is what makes this reliable rather than the push notification. A notification from GitHub is an optimisation — if one is ever lost, the scheduled check finds the change a few minutes later instead of never. It is also the only thing that notices two situations a notification cannot: a repository that disappeared from the installation, and a document someone edited in the web.
Only one run per pairing happens at a time. A push and a scheduled check arriving in the same second do not produce two runs.
Reading a run
| Status | What it means |
|---|---|
| Queued | Recorded, not started yet |
| Running | In flight |
| Succeeded | Finished the whole revision |
| Partial | Stopped at its budget — what it did is kept, and the next run continues from there |
| Failed | Could not complete |
Partial is not a failure. A very large change is worked through across several runs, and nothing is lost between them. A partial run also deletes nothing at all — “not in the part I read” is not the same as “gone”.
Into the repository: one living pull request
Edits made in Meldoc go out on a branch named meldoc/sync/<project-alias>, as a single open pull request. Further edits arrive as new commits on the same pull request. Merge it and the next edit opens a fresh one.
That branch is never force-pushed and never rebased. A pull request carries review comments anchored to its commits, and rewriting the branch would strip them and break anyone’s checkout. When the branch falls behind, the default branch is merged into it instead.
Until you merge that pull request, Meldoc does not treat the exported text as agreed. That is why an edit can still turn into a conflict after it has been exported — nothing is settled by sending it.
Deletions
A file that disappears from the repository removes the document, or archives it, depending on one project setting — the same Documents deleted via CLI setting the CLI obeys. See Archiving Documents.
The exception is a document that has unsynced edits made in Meldoc. That is not deleted quietly; it becomes a conflict for a person to decide. See Resolve a Conflict.
In the other direction, archiving a document removes its file from the repository: the repository reflects the living documentation, and the archive is a Meldoc idea with nothing to correspond to. A file the sync never wrote is never deleted.
One project, several repositories
A project can be fed from more than one repository — an API, a worker and a mailer each keeping their own section of one documentation tree. Each repository is subscribed to the project on its own, and each one’s meldoc.config.yml says which part of the project is its business with scope, the same setting the CLI reads:
workspaceAlias: acme
baseDirs:
- projectAlias: platform
baseDir: docs
scope:
- postal
A run reads only the documents under the aliases the scope names — with their descendants unless scopeChildren: false — and pushes only those into that repository’s pull request. A document outside the scope is another repository’s, whatever folder it sits in: it is neither exported there, nor deleted when its file goes.
Without a scope every subscription takes the whole project, and with three repositories that means three pull requests each carrying all three repositories’ documentation. The panel shows what each subscription is limited to, read from the config on every run, so a missing or mistyped scope is visible without opening the repository. See Configuration for the setting itself.
Images
Images referenced by a document are uploaded as assets, the same way meldoc push uploads them. If one cannot be fetched, the run warns and imports the document anyway — a page does not fail to arrive because of its picture.
What’s next?
Resolve a Conflict — When both sides changed the same file.
Pre-Merge Check — See what a sync will do before the pull request merges.