Synchronization and managed-file behavior¶
One complete bounded reconciliation¶
Every manual, scheduled, retried, or rebuilt run performs a bounded full reconciliation:
- Complete the paginated Confluence page inventory.
- Fetch and convert every in-scope page from ADF.
- Resolve the complete page path and internal-link map.
- Materialize every generated page and eligible referenced image.
- Compare the complete desired tree with the current Git tree and a valid prior ownership manifest.
- Reuse byte- and hash-identical Git blobs.
- Create one complete justified commit, or no commit when nothing changed.
- Update or create only the dedicated non-default target ref without force.
- Reread the ref, commit, and manifest before recording durable success.
An incomplete source inventory, unsafe page output, limit breach, ownership failure, collision, or stale publication fence prevents a Git ref update. Conf2Git never makes a destructive plan from a partial inventory.
Exact public-v1 limits¶
| Limit | Maximum |
|---|---|
| Pages per mapping and run | 1,000 |
| Generated files per run, including the ownership manifest | 1,500 |
| Individual image | 10 MiB |
| Aggregate image bytes per run | 64 MiB |
| Generated bytes per run, including the ownership manifest | 100 MiB |
| Mappings that have not been removed per Confluence site | 5 |
These are supported ceilings, not targets. A run over any applicable limit fails before
publication with PUBLIC_V1_LIMIT_EXCEEDED. Conf2Git does not claim support beyond them.
Managed and unowned files¶
Managed files are the paths listed in a valid prior ownership manifest, plus the canonical manifest itself only after its identity and publication provenance validate. A filename pattern, base-path location, front matter, or stored claim does not establish ownership.
Confluence is authoritative for provenance-valid managed files. If a person edits one of those
files in GitHub, a later reconciliation may replace the edit and reports
GITHUB_MANAGED_FILE_MODIFIED. Treat the dedicated branch as generated output.
Every other current repository path is unowned and is preserved byte-identically. Conf2Git never
silently claims an existing path. A desired new file that collides with an unowned exact path,
file/directory ancestor or descendant, case-folded path, or Unicode-normalized path fails with
MANIFEST_OWNERSHIP_CONFLICT and publishes nothing.
Source changes¶
| Confluence observation | Mirror behavior after a healthy complete reconciliation |
|---|---|
| Page added or edited | Add or update the generated page and any justified image/link output. |
| Page renamed or moved | Move the page and affected descendants; recalculate internal links in the same complete candidate commit. |
| Page explicitly archived or definitively deleted | Remove only its prior manifest-owned managed page and image paths. |
| Page-specific access lost while mapping-wide access remains healthy | Remove the managed mirror promptly and report CONFLUENCE_PAGE_ACCESS_LOST. |
| Page ambiguously missing | Keep output after the first complete miss; removal requires a second consecutive complete miss. |
| Page returns or is proven outside the mapping | Preserve output and reset any eligible pending-removal observation after a successful boundary. |
| Mapping-wide authorization, pagination, inventory, conversion, or source proof fails | Remove nothing and publish no ref update. |
Pending removal is a safety state, not proof that a page was deleted. Entitlement or GitHub authorization loss never authorizes cleanup.
No-change runs and publication races¶
A no-change run reuses matching blobs, creates no commit, and performs no ref update. The last successful content provenance remains the previously published commit, while the operational mirror time may be refreshed.
For a changed run, the existing target head must still match the captured head at publication. An absent target must still be absent. If another writer moves the branch, Conf2Git retries within a bounded policy or fails safely; it never force-pushes.
Rebuild, repair, and removal boundaries¶
- Rebuild performs another complete source reconciliation. It may regenerate, replace, move, or remove only provenance-valid managed files and preserves every unowned file.
- Manifest repair may restore exactly one canonical ownership-manifest path from independently verified historical provenance. It does not change pages or images, move files, or delete any path.
- Remove mapping deletes stored mapping and binding metadata but leaves all repository output in place.
- There is no public-v1 operation that removes all generated files.
Review the exact dry-run plan and confirmation requirements in Recovery and lifecycle operations.