Connect Confluence
For organisation admins. Connects your Speclr organisation to Confluence Cloud once, so project teams can keep their requirements documentation as pages below a Confluence page they choose.
Updated
Use a dedicated machine account
- Clear authorshipConfluence shows the connected account as the author of every page version Speclr writes.
- Survives people leavingA personal account takes the wiki updates down with it when its owner leaves.
- Only the spaces it needsSpeclr can write wherever the account may write. An account added to the documentation spaces only cannot touch anything else.
Speclr writes to Confluence: it keeps your project's requirements documentation as pages below a page you choose. It never imports anything from Confluence. Speclr works with Confluence Cloud; Confluence Data Center cannot be connected.
Create the account and add it to your spaces
Create an Atlassian account such as
speclr-bot@acme.comwith a team mailbox and give it access to Confluence on your site. If you already have one for Jira, you can use the same account. In each space your project teams will document in, let it view the space and create and edit pages: the space role "Collaborator" does both, as does the permission "Add" for pages.- Two-step verification on, recovery codes stored with the team
- Access to one Atlassian site only, so Speclr connects to the right one
- Create and edit pages in each documentation space, no space admin rights
Connect in Speclr, signed in as the machine account
Open Organisation settings › Integrations › Discover and choose "Connect" on Confluence. Only organisation admins see the integrations. When Atlassian asks you to sign in, use the machine account, not your own. A private browser window avoids mix-ups.
Atlassian then shows "Speclr is requesting access to your Atlassian account" and lists Confluence permissions only. Speclr requests the scopes
offline_access read:confluence-user read:space:confluence read:page:confluence write:page:confluence read:hierarchical-content:confluence read:user:confluence. You only consent; the scopes are set by Speclr.Speclr uses its own Atlassian app for Confluence, separate from the one for Jira. Connecting Confluence leaves a Jira connection as it is, and Confluence works without Jira.
Back in Speclr, the connection appears under Yours and reads "Acts as" the account "on" your site. Check both.
Check the permissions
The scopes let Speclr do no more than the account itself may do in each space. Speclr uses them for:
- Spaces
- read, to list them in the project settings
- Pages
- read, create and update below the parent page
- Page tree
- read, to find its own pages below the parent page
- Users
- read names, to show who edited a page
- Comments and attachments
- none
Pick the parent page in each Speclr project
Any member of a Speclr project can do this. Open Project settings › "Integrations". The "Parent page" row reads "Confluence is connected. Choose a space, then a page in it." Choose "Choose page" and pick a space. The list shows your spaces with their keys first, and personal spaces last, labelled "Personal space".
Speclr proposes the space's homepage, for example "Below Shop Home, the homepage of Shop." Choose "Use this page", or search another page of the space. "Change space" goes back to the list. If Notion is connected too, one list shows the Notion pages and, under "Confluence spaces", the spaces.
Once saved, the row reads "Saved · the page was found in Confluence". Speclr then asks "Put the requirements documentation into Confluence?". Choose "Put it in" to create the pages. With "Not now", the row keeps "Not in Confluence yet" with "Put it in…" for later. Speclr needs a committed version of the Discovery first.
Afterwards, the row's "Pages" line links the project page "In Confluence" and shows the last sync, for example "Last sync · 2 updated · 9 unchanged" after a commit.
What Speclr creates in Confluence
Below the parent page, Speclr creates one project page, for example Shop – Requirements for a project named Shop. Below it come the documentation pages. They follow the req42 framework and keep its numbers. Confluence allows each title only once per space, so every title starts with the project's name, for example Shop – 1. Vision and goals:
- 1. Vision and goals, 2. Stakeholders, 3. Scope and 4. Product backlog: the vision, the target users and actors, the first milestone, and the epics, features and user stories with their hand-over status.
- 5. Supporting models, 6. Quality requirements, 7. Constraints and 8. Domain terminology: the business rules and data fields, the non-functional requirements, the constitution and the glossary.
- 11. Roadmap and 12. Risks and assumptions: the milestones in order, and the risks from the vision, with the risks your team tracks below them.
The pages hold the same content as in Notion; Connect Notion describes each section. Every page starts with an info panel such as "Generated by Speclr · edit in Speclr · exported 2 Nov 2026". The pages show committed versions only, so an open draft does not appear.
Speclr writes each page whole. Every update is a new page version with the message "Speclr hand-over" in the page history; a page whose content did not change gets no new version. Your team can add its own pages inside the project page; Speclr never changes, moves or deletes them.
Edit in Speclr, not in Confluence
These pages are Speclr's from top to bottom. Change the content in Speclr. After each commit, Speclr updates the affected pages on its own and leaves the others alone.
If a Speclr page has a newer version than the one Speclr wrote, someone edited it, and Speclr does not overwrite it. A new title counts as an edit too. The "Wiki" row says, for example, "Shop – 5. Supporting models was edited in Confluence." "Resolve…" compares "Written by Speclr" with the page in Confluence now, names who edited it, and offers two ways out:
- Keep the Confluence version: later versions are not written to that page. "Replace…" undoes that later.
- Replace with the Speclr version: Speclr writes its version over the edit, as the page's next version.
A page deleted in Confluence or moved to the trash shows, for example, "Shop – 8. Domain terminology no longer exists." Choose "Recreate the page", or "Detach" to let Speclr forget it. Nothing is ever imported from Confluence into Speclr.
Choosing another parent page later leaves the old pages in Confluence. Speclr no longer updates them.
Limits
- A page title can exist only once per space. If a page of the same title exists elsewhere in the space, for example
Shop – 3. Scopefrom an earlier copy, Speclr cannot create that page in the space. Troubleshooting shows the message. - Atlassian limits requests per app, across all organisations that use Speclr, not per organisation. A project's page tree stays far below that limit.
- Unpublished changes someone has open in Confluence's editor on a Speclr page can be lost when Speclr updates it. Edit Speclr's pages in Speclr.
Reconnect or disconnect
Reconnect when the connection shows "Nothing is handed over until it is reconnected", as the same machine account. Atlassian also asks for consent again whenever Speclr's scopes change. Another account first names the affected projects.
Disconnecting first names the affected projects. Their parent pages and the pages in Confluence stay; Speclr stops updating them.
Troubleshooting
- Atlassian shows "Access denied" with "This app requires access to a Confluence site which you don't have": the account in the consent window has no active Confluence access on the site. Accept the site invitation, check its product access under admin.atlassian.com, and make sure you are signed in to Atlassian as the machine account.
- A space is missing from the list: the machine account cannot view it. Add it to the space.
- "Speclr can no longer write below Shop Home. Ask a Confluence admin for permission to edit pages in the space, or choose another page.": give the account permission to create and edit pages in the space.
- "Speclr may not edit Shop – 5. Supporting models in Confluence. The Speclr connection needs permission to edit pages in this space.": the same permission is missing.
- "Shop Home was deleted or moved to the trash in Confluence. Choose another page.": restore the page from the space's trash, or choose another parent page.
- "A page titled Shop – 1. Vision and goals already exists in this Confluence space. Rename that page in Confluence, or choose a parent page in another space.": see Limits.
- "Commit a version of the Discovery first.": the documentation starts from the vision. Commit the Discovery once, then put it in.
- "An admin must reconnect the Confluence connection.": reconnect as the machine account, with access to one site only. The same applies when the connection names the wrong site.
- A change made in Confluence is not in Speclr: Speclr never imports. Make the change in Speclr and commit it.
