Documentation
Version 1.0 · Effective November 1, 2026
Doc Drift flags Confluence pages that mention files a merged GitHub pull request changed or removed. This guide covers setup and everyday use.
1. Install
A Confluence admin installs the app from the Atlassian Marketplace and approves its permissions. From then on, the app indexes each page when it is created or edited. Pages that haven't been edited since install are checked after their next edit.
2. Connect GitHub
The app learns about merged pull requests from a GitHub push webhook. You need to be a Confluence admin and an admin of the GitHub repository.
- In Confluence, open Settings → Doc Drift (under the apps section of the admin settings).
-
In the GitHub section, click Copy webhook URL (or select the URL in the Web trigger URL field and copy it). This URL is unique to your site; treat it like a password.
-
Under New webhook secret, type a random secret of 20 or more characters and click Save secret. The page then shows "A webhook secret is set." The secret is never shown again.
- In GitHub, open the repository's Settings → Webhooks → Add webhook. Paste the URL, set the content type to
application/json(application/x-www-form-urlencodedalso works), paste the same secret, and choose Just the push event.
GitHub sends a test ping when you add the webhook; the app ignores it. Repeat step 4 for each repository. One secret is used for all of them.
The app reads only pushes to the repository's default branch, and only file names, never code. Notices without a valid signature are rejected (GitHub shows status 401). A signed notice the app can't read is refused with status 400.
You can send the same notice from a GitHub Action instead of, or as well as, the webhook. Copy github-action/doc-drift-notify into the repository and point it at the same URL and secret. By default it sends no owners. Set the optional codeowners input to true (and check out the repository first) to send GitHub team slugs such as @org/team from your CODEOWNERS file. The Action does not send individual GitHub usernames or email addresses. The page popup shows those team slugs until someone clears the flag. The setup steps are in the repository README. The Action is not published to the GitHub Marketplace.
3. Settings
Confluence admins can change these on the same settings page. Click Save to apply them.
| Setting | What it does | Default |
|---|---|---|
| Flag threshold | How sure the app must be before it flags a page, from 0.30 to 0.95. Higher means fewer flags. | 0.5 |
| Only merged pull requests | Act only on pushes whose latest commit is a pull request merge or squash, such as Merge pull request #123 or ... (#123). |
On |
| Space to repos | One line per space: SPACEKEY=owner/repo,owner/repo2. Pages in that space match only those repositories. Leave it empty to let every space match every repository. |
Empty |
| Ignore paths | File patterns to skip, comma separated, such as docs/**, *.test.ts. |
None |
| Freshness marker | When on, a drifted page's byline tooltip adds one sentence for readers and Rovo, and the app saves a freshness marker (status and time only) that CQL can search as ab500DriftFreshness. |
Off |
The page also shows how many pages the app can't read because of page restrictions or app access rules. Those pages are never flagged.
4. How pages get flagged
When a page is created or edited, the app looks for code references in it: file and folder paths, web routes, configuration keys and environment variable names, in code blocks, inline code, GitHub links and plain text.
When a matching push arrives, the app compares the changed and removed file names with each page's references. A removed file counts more than a changed one, and an exact path counts more than a matching file name or folder. References in code formatting count more than ones in plain text. A page is flagged when its score reaches the threshold.
Some limits keep flags useful:
- Common root files such as
package.jsonorREADME.mdcount very little when changed. - For a push that touches more than 200 files, only removals count.
- At most 25 pages are flagged per push.
5. Review a flagged page
A flagged page shows Possibly outdated since PR #N in its byline. Hover for a short explanation, or click it to open the details: the score, how many changes have flagged it, and each reference on the page that matched, such as "src/payments/retry.ts — file removed". If the push came from the GitHub Action with CODEOWNERS turned on, the popup also lists GitHub team slugs (@org/team) for the changed files. It does not list individual usernames or email addresses.
When an admin has turned the freshness marker on, the byline tooltip also says "Readers and Rovo should treat this page as possibly stale." That sentence is part of the byline property, not the page body.
Anyone who can view the page can resolve the flag:
- Still accurate marks the page Verified. A later pull request can flag it again.
- Not relevant marks it Not relevant and stops the same references from flagging that page again.
The App doesn't record who cleared a flag.
6. Find flagged pages with CQL
Use these fields in Confluence search (CQL):
| Field | Example |
|---|---|
ab500DriftStatus |
ab500DriftStatus = "possibly_outdated" (also verified, not_relevant) |
ab500DriftScore |
ab500DriftScore >= 80 |
ab500DriftLatestPr |
ab500DriftLatestPr = 482 |
ab500DriftOpenFlags |
ab500DriftOpenFlags > 1 |
ab500DriftFlaggedAt |
ab500DriftFlaggedAt > "2026-11-01" |
ab500DriftRepo |
The repository, with its owner replaced by a short code (the repository name itself is not changed) |
ab500DriftSchema |
The summary format version |
ab500DriftFreshness |
stale or current, only on pages where an admin had the freshness marker on |
ab500DriftFreshnessAt |
When that marker was last written |
Search results only include pages you can view.
7. AI tools (MCP)
The app offers two read-only tools through Atlassian's MCP service, so an outside AI tool can ask about drift:
- Find possibly outdated pages: lists flagged pages (optionally in one space, up to 50).
- Check page drift: the status of one page, the pull request, the score and up to five matched references.
They run as the person using them and return only pages that person can view. They are off unless a site admin allows outside AI tools through Atlassian's MCP service. This part of the app uses an Atlassian module that is in Preview.
Inside Atlassian, custom Rovo agents can use these tools for people who can already see the pages. Sending them to an outside AI tool is off unless a site admin turns it on.
8. Licensing
If the site's license isn't active, the app doesn't index pages or act on GitHub notices. The byline says "Doc Drift license is inactive." and the settings page shows a warning.
9. Uninstall
A Confluence admin uninstalls the app from Apps → Manage your apps. Delete the webhook in each GitHub repository too.
The app's settings and index are deleted by Atlassian. The content properties stay on flagged pages until an admin removes them with Confluence's REST API:
DELETE /wiki/rest/api/content/{id}/property/ab500_drift_v1DELETE /wiki/rest/api/content/{id}/property/ab500_drift_byline_0ddac1f1DELETE /wiki/rest/api/content/{id}/property/ab500_drift_freshness_v1when the freshness marker was saved- Or, on the v2 API:
DELETE /wiki/api/v2/pages/{id}/properties/{property-id}for each of these properties.
While the App is installed, an admin can find every page the App has marked with the CQL search ab500DriftSchema >= 1. That search stops working after an uninstall. We also provide a script that finds and removes these properties, including after an uninstall (see Removing the App's page properties), or email support@archbadger500.com and we'll help.
Removing the properties is described in section 10.
See the Privacy Policy for details, and the support page for help.
10. Removing the App's page properties
The App saves content properties on pages it flags: ab500_drift_v1 (the summary), ab500_drift_byline_0ddac1f1 (the byline text), and, only when an admin turned the freshness marker on, ab500_drift_freshness_v1 (a status and a time). They are stored in Confluence, so they stay on those pages after you uninstall the App. We provide a script that removes them from every page that has them. It never changes page text, titles, labels or comments. Email support@archbadger500.com and we'll send you the script.
- What you need: Node.js 22 or newer, and a Confluence account that can edit the pages, with an API token. The script reads your site address, email and token from environment variables (
CONFLUENCE_SITE,CONFLUENCE_EMAIL,CONFLUENCE_API_TOKEN). It sends the token only to your site and never prints it. - Dry run by default:
node remove-properties.jslists the pages that have the properties and deletes nothing. - Delete with
--yes:node remove-properties.js --yesremoves these properties with Confluence's v2 API (DELETE /wiki/api/v2/pages/{id}/properties/{property-id}). - One space: add
--space KEYto limit the run to one space. - After an uninstall: the search the script normally uses (
ab500DriftSchema >= 1) works only while the App is installed. After an uninstall, use--scan --space KEYto check every page in a space, once for each space. - Safe to run again: it waits and retries when Confluence rate-limits it, and a property that is already gone counts as removed. It exits with an error code and lists the pages it couldn't change, for example pages your account can't edit.