Inspiration
API documentation in Confluence goes out of date quietly. The spec changes in a pull request, the code ships, and the page that tells other teams how to call the endpoint still describes the old version. Nobody finds out until someone integrates against it and it fails. The spec already says exactly what changed, so the docs should be able to find out too.
What it does
Plumbline connects an OpenAPI spec to a Confluence space and watches it.
- Every new version is diffed against the last one: removed endpoints, newly required fields and parameters, removed fields, type changes, removed enum values, auth changes and removed status codes are breaking; additions and description changes are reported as other changes. It reads OpenAPI 2.0, 3.0 and 3.1, as JSON or YAML.
- The right pages are flagged. Plumbline searches the space for pages that mention a changed endpoint, operation ID or schema, and flags each one with the exact change, the text it matched and how confident the match is. A page that only says "Order" in passing isn't flagged; a page that documents
POST /v1/ordersis. - Drift shows up where people read: a one-line banner on flagged pages with View changes and Mark as reviewed, an optional in-page card macro, and an API drift report in the space sidebar.
- Owners hear about it once a day. A digest page assigns a Confluence task to the owner of each newly flagged page, so nobody gets a notification per change.
- History is kept on a page under the spec, listing every version and what changed.
- Endpoints can be shown straight from the spec with the Plumbline API endpoint macro, with change badges and a curl example, so reference sections never drift in the first place.
- Pull requests are checked. A CI step for Bitbucket Pipelines or GitHub Actions sends the proposed spec to Plumbline. Breaking changes without a major version bump fail the build. Bumping the major version passes the check, and when that release merges, the affected pages are flagged. On Bitbucket Premium, a failed check can block the merge.
Plumbline never edits page content. It flags, and people fix.
How it was built
Plumbline is a Forge app on Confluence, built with UI Kit and plain JavaScript, and it runs entirely on Atlassian with no outbound calls.
- A product event trigger picks up new versions of spec attachments.
- A static web trigger receives CI pushes and pull request checks, authenticated with a per-spec secret kept in Forge secret storage.
- A Forge queue consumer does the page matching, which can read hundreds of pages, with a 15 minute timeout.
- A scheduled trigger writes the daily digest.
- Forge storage holds flags, diffs, history and endpoint summaries.
- The UI is a space settings page, a page banner shown only on flagged pages through a display condition on a content property, a space page report, and two macros.
The diff engine and the page matcher are pure modules with their own test suite (100 tests), including real spec fixtures and a shell test that runs the generated CI commands against a local server.
Challenges
- Getting specs through the web trigger intact. Raw YAML bodies arrived with their newlines stripped, which turns a valid spec into an invalid one. Pipelines now send the spec gzipped and base64-encoded inside a small JSON envelope, with a 5 MB limit enforced after decompression.
- Matching without false alarms. A schema called "Order" appears in a lot of prose. One-word schema names only count when they're written as inline code, and every flag carries the matched excerpt so a reviewer can judge it in seconds.
- Long-running work in Forge. Product triggers can't run for long, so matching moved to a queue consumer with an inline fallback.
- Telling intentional breaks from accidents. The CI check uses the spec's own major version: a breaking change in 2.4.0 fails, the same change in 3.0.0 passes, and the docs are flagged either way once it ships.
Accomplishments
- The whole loop works end to end: a pull request fails on a breaking change, the major release passes, and the moment it merges, the exact pages that describe the old behaviour are flagged with the lines that need fixing.
- It runs entirely on Atlassian and is eligible for Runs on Atlassian.
- It's submitted to the Atlassian Marketplace as a paid app with a free tier for up to 10 users.
What was learned
Forge's constraints shaped the design for the better. Static web trigger responses, queue consumers and display conditions pushed Plumbline towards small, predictable pieces, and keeping all data on Atlassian made the privacy and security story simple to explain.
What's next
- Marketplace launch once the listing review completes
- Support for specs split across multiple files
- Matching in Jira issues and Bitbucket READMEs, not only Confluence pages
- A free endpoint viewer tier for larger teams
