11. Risks and Technical Debt

Risks

ID Risk Mitigation Severity

ID	Risk	Mitigation	Severity
R1	The v1 attachment endpoint disappears. Attachment upload depends on a v1 operation because REST v2 cannot create attachments. If Atlassian retires v1 before closing the gap, attachments break.	The operation is not marked deprecated, and the gap is tracked upstream as CONFCLOUD-77196. The dependency is isolated in one API class, so a replacement is a local change. Watch the issue.	high
R2	Antora’s HTML structure changes. The parser reads the navigation panel via `data-panel="menu"` and `data-depth`, and page content via `article.doc`. These are properties of Antora’s default UI, not a documented contract.	Pinned Antora and UI bundle versions in the sample. An upgrade shows up immediately as an empty or wrong page tree. `parserClass` allows a replacement parser without touching the core.	high
R3	Page titles must be unique per space. Confluence identifies pages by title within a space, and the link index is keyed the same way. Two documentation pages with the same title collide.	Duplicates surface as pages overwriting each other. Not currently detected or reported — see debt D3.	medium
R4	API rate limits on large spaces. A first publish of a big site issues many requests in a short window. Confluence Cloud throttles.	The content hash keeps subsequent runs small, and requests are retried once. A first run against a very large site remains untested at scale.	medium
R5	Single maintainer. Bus factor of one, on a tool that other builds may depend on.	Apache 2.0, published sources and javadoc on Maven Central, and this documentation. A fork is possible without the maintainer.	medium
R6	Confluence normalises stored content. If normalisation ever affected what we hash, change detection could produce false positives and rewrite pages.	The hash is computed over our own transformation output, before sending, so remote normalisation cannot influence it by design.	low

The v1 attachment endpoint disappears. Attachment upload depends on a v1 operation because REST v2 cannot create attachments. If Atlassian retires v1 before closing the gap, attachments break.

The operation is not marked deprecated, and the gap is tracked upstream as CONFCLOUD-77196. The dependency is isolated in one API class, so a replacement is a local change. Watch the issue.

high

Antora’s HTML structure changes. The parser reads the navigation panel via data-panel="menu" and data-depth, and page content via article.doc. These are properties of Antora’s default UI, not a documented contract.

Pinned Antora and UI bundle versions in the sample. An upgrade shows up immediately as an empty or wrong page tree. parserClass allows a replacement parser without touching the core.

high

Page titles must be unique per space. Confluence identifies pages by title within a space, and the link index is keyed the same way. Two documentation pages with the same title collide.

Duplicates surface as pages overwriting each other. Not currently detected or reported — see debt D3.

medium

API rate limits on large spaces. A first publish of a big site issues many requests in a short window. Confluence Cloud throttles.

The content hash keeps subsequent runs small, and requests are retried once. A first run against a very large site remains untested at scale.

medium

Single maintainer. Bus factor of one, on a tool that other builds may depend on.

Apache 2.0, published sources and javadoc on Maven Central, and this documentation. A fork is possible without the maintainer.

medium

Confluence normalises stored content. If normalisation ever affected what we hash, change detection could produce false positives and rewrite pages.

The hash is computed over our own transformation output, before sending, so remote normalisation cannot influence it by design.

low

Technical Debt

ID Debt Consequence

ID	Debt	Consequence
D1	No automated end-to-end assertion. `confluence.yml` publishes this documentation to a real space on every relevant push, so the API interaction is exercised continuously — but nothing asserts the result. The build fails only when the publisher throws, not when it writes something wrong. The tests covering a live instance remain local integration tests (`*TestLocal`), excluded from the repository and from CI.	A regression that produces valid-but-wrong output — a mangled link, a lost admonition — passes CI unnoticed and is only found by looking at the space. `updatePages` and `syncPageStructure` still have no covering unit test.
D2	Maven is the only entry point. `wiki-publisher` is Maven-free by design, but no CLI, Docker image or Gradle plugin exists to prove or exploit it.	Documentation pipelines that do not use Maven cannot use the tool at all, which is the largest restriction on who can adopt it.
D3	Duplicate page titles are not detected. The link index silently keeps one entry per title/space pair.	Two pages with the same title in one space overwrite each other without a warning. A check during index construction would turn this into a reported error.
D4	The OpenAPI specification is patched by hand. Four `likes/count` response titles must be renamed after every refresh from Atlassian, or the generated sources do not compile.	Refreshing the spec is a manual ritual documented only in the `wiki-client` README. A patch file or a generator configuration override would make it reproducible.
D5	Fixed version numbers in the READMEs. Installation snippets name a concrete version that has to be updated at every release.	Snippets drift out of date silently. Mitigated by a Maven Central badge next to them, but the snippet itself still needs the manual edit.
D6	Two OpenSSF Scorecard checks cap out for the same reason. Branch-Protection caps at Tier 1 (3/10): higher tiers require a pull request with at least one approving review, and GitHub does not let an author approve their own pull request. Code-Review scores lower still — it looks at whether the last ~30 commits were actually reviewed by someone else, not whether a rule is configured, so a single maintainer pushing directly scores at or near 0 regardless of settings.	Accepted rather than worked around, as a direct consequence of OC3 (2. Architecture Constraints). Requiring pull requests would not move the Code-Review score without a second collaborator, and routinely bypassing a self-imposed review requirement would trade real workflow friction for a score that does not reflect an actual second set of eyes.

No automated end-to-end assertion. confluence.yml publishes this documentation to a real space on every relevant push, so the API interaction is exercised continuously — but nothing asserts the result. The build fails only when the publisher throws, not when it writes something wrong. The tests covering a live instance remain local integration tests (*TestLocal), excluded from the repository and from CI.

A regression that produces valid-but-wrong output — a mangled link, a lost admonition — passes CI unnoticed and is only found by looking at the space. updatePages and syncPageStructure still have no covering unit test.

Maven is the only entry point. wiki-publisher is Maven-free by design, but no CLI, Docker image or Gradle plugin exists to prove or exploit it.

Documentation pipelines that do not use Maven cannot use the tool at all, which is the largest restriction on who can adopt it.

Duplicate page titles are not detected. The link index silently keeps one entry per title/space pair.

Two pages with the same title in one space overwrite each other without a warning. A check during index construction would turn this into a reported error.

The OpenAPI specification is patched by hand. Four likes/count response titles must be renamed after every refresh from Atlassian, or the generated sources do not compile.

Refreshing the spec is a manual ritual documented only in the wiki-client README. A patch file or a generator configuration override would make it reproducible.

Fixed version numbers in the READMEs. Installation snippets name a concrete version that has to be updated at every release.

Snippets drift out of date silently. Mitigated by a Maven Central badge next to them, but the snippet itself still needs the manual edit.

Two OpenSSF Scorecard checks cap out for the same reason. Branch-Protection caps at Tier 1 (3/10): higher tiers require a pull request with at least one approving review, and GitHub does not let an author approve their own pull request. Code-Review scores lower still — it looks at whether the last ~30 commits were actually reviewed by someone else, not whether a rule is configured, so a single maintainer pushing directly scores at or near 0 regardless of settings.

Accepted rather than worked around, as a direct consequence of OC3 (2. Architecture Constraints). Requiring pull requests would not move the Code-Review score without a second collaborator, and routinely bypassing a self-imposed review requirement would trade real workflow friction for a score that does not reflect an actual second set of eyes.

R1 and R2 are the two risks that can break the tool without any change on this side. Both are external contracts that are not versioned as such — which is why both are worth watching actively rather than waiting for a bug report.