How to use Jira and Confluence together

The short answer

Jira is where the team tracks the work: each piece of work is a ticket with a status. Confluence is where the team writes things down: plans, requirements, meeting notes and how-to pages. You use them together by putting Jira inside Confluence pages and linking Confluence pages from Jira tickets, so the document explains the why and the tickets show where the work is.

In Jira Cloud and Confluence Cloud, most of it works by pasting a link. Paste a ticket's link into a Confluence page and it shows the ticket's key, title, type and current status. Paste a search link and you get a list of tickets. Paste a board's link and the board appears on the page. You can also highlight text on a page and turn it into a new ticket. The sections below show each one step by step.

What each tool is for

Atlassian describes Jira as the tool that helps a team "plan and track project work", and Confluence as the place to "organize all of the ideas, content, and files" a team creates. A simple way to remember it:

Imagine the payments team. Mira, the product owner, writes a Confluence page called "Receipts redesign: requirements". The work itself lives in Jira as an epic, PAY-120, with stories and bugs under it (see what an epic is). The page explains what the team is building and why. The tickets show who is doing what and how far along it is. Linking the two means nobody has to copy a status by hand into a document that is out of date by Friday.

One naming note: Atlassian's current Cloud help says work items where older pages and many colleagues say issues or tickets, and spaces where people used to say projects. Confluence has always used "space" for its own areas, so the word now appears in both tools.

Step 1: Show one ticket on a page

This is the answer to "how do I show Jira status in Confluence". You do not type the status; you paste the ticket and Confluence shows it.

1. Open the ticket in Jira, for example PAY-142, and copy its link from the browser's address bar.
2. In Confluence, open the page and select Edit.
3. Paste the link where you want it.
4. Select Save or Publish.

Atlassian's guide says the pasted link then shows the work item's key and title, its work type (epic, task and so on) and its status. Because the link is read from Jira, the status changes on the page when the ticket moves on the board. Nobody has to remember to update it.

Every link in Confluence is a Smart Link, and you can choose how it looks. Select the link and pick a view from the toolbar: URL shows the full address, Inline shows the title as text, Card shows a short summary and Embed shows an interactive preview.

Step 2: Show a list of tickets, such as an epic

For a whole epic or a set of tickets, use the Jira work items macro. It can show one ticket, a list or just a count.

1. While editing the page, type /jira and select Jira work items.
2. Search for the tickets you want. You can search by space, or with Jira's query language (JQL). To list everything in an epic, search on the parent field, for example parent = PAY-120.
3. Select Display options to choose the columns, drag them into the order you want and set how many tickets appear.
4. Insert the macro and publish the page.

Two shortcuts are worth knowing. If you already have a search or saved filter open in Jira, paste its link straight onto the page and Confluence turns it into the macro for you. And if a manager only wants a number ("how many bugs are still open?"), choose Display options then Total work item count: the page shows a count that links back to the search in Jira.

This is also how you "link an epic in Confluence": paste the epic's own link for a single line with its status (Step 1), or list its tickets with the macro. To connect the page to the epic from the Jira side as well, see Step 5.

Step 3: Embed a whole board

Yes, you can embed a Jira board in Confluence. Atlassian's help covers boards and backlogs, and its Confluence guide adds dashboards, gadgets and releases.

1. Open the board (or backlog) in Jira.
2. At the top, select the share icon, then Copy link.
3. In Confluence, create a page or edit an existing one.
4. Paste the link. It appears as a Smart Link in embed view, an interactive preview of the board.
5. Publish the page.

A team page with the board embedded at the top gives visitors from other departments one place to look. If you only want the link in a space's page tree, Confluence also lets you add it as a Smart Link there: select Create and then Smart Link, paste the board's URL and select Add Smart Link.

Step 4: Create tickets from page text

Meeting notes are full of action items. Instead of copying each one into Jira later, turn the text into tickets from the page.

1. On the published page, highlight the text, for example "Ask Legal to check the new receipt footer".
2. Select + Jira work item in the toolbar that appears.
3. Select Create single work item.
4. Fill in the fields in the side panel (space, work type, summary) and select Create.

If the action items are in a table, highlight the table text, select + Jira work item, then choose the option for multiple work items to create one ticket per row. On Premium and Enterprise plans with Atlassian's AI (Rovo) turned on, Confluence can also suggest the summary and description from the surrounding text; you can switch that off with Use AI to generate summary and description.

Atlassian notes there are some limitations on creating tickets this way; the dialog tells you when it cannot create a ticket in the space you picked. And a ticket created from a page is still a ticket: give it a summary that makes sense on its own, because on the board nobody sees the meeting notes around it.

Step 5: Link pages from the Jira side

Links work in both directions. To connect a whole Jira space to a Confluence space, Atlassian's guide says to go to Pages in the Jira space's navigation, select Connect to Confluence and search for the Confluence space.

To link the requirements page to an epic in a company-managed space:

1. Open the epic in Jira, for example PAY-120.
2. Select + to add or create related work.
3. Select Page, then Link page, and pick the existing Confluence page.

Once a page has Jira links, Confluence shows a Jira Links button at the top of the page. Its number counts all the linked work items and sprints, so a reader can jump from the plan to the work in one click.

A live status vs a typed status

Confluence also has a status label of its own: type /status while editing and you get a coloured lozenge (grey, red, yellow, green or blue) with your own text, such as "On track". That label is typed by a person and changes only when someone edits it. It does not read anything from Jira.

So when someone asks you to "add the Jira status" to a page, ask whether they mean the pasted ticket from Step 1, which follows the ticket. A typed label suits a summary judgement on a whole project ("At risk"), not the status of one ticket.

Who sees what

Putting a ticket on a page does not give anyone access to it. Atlassian's help says the Jira Links dropdown only shows the work items you have permission to view, even though its count includes them all. The Data Center help for the Jira macro says the same for lists: by default it shows only the tickets each reader is allowed to see. If a colleague says the list on your page is empty for them, check their access to the Jira space before you rebuild the page.

Jira Cloud vs Jira Data Center

The steps above follow Atlassian's Cloud help. On Data Center, Confluence and Jira must first be connected by an admin through Application Links, and the help still calls the list macro the Jira Issues macro. In a table it shows type, key, summary, assignee, reporter, priority, status, resolution, created, updated and due date by default, and the reader may be asked to log in to Jira to see restricted tickets.

Practise the Jira half first

Every one of these steps starts in Jira: finding the right ticket, reading its status and knowing which epic it belongs to. A Confluence page only shows what the tickets say. Agile Board Practice has a lesson on finding anything, where you search by key and by word and read which epic a ticket belongs to, and a workplace practice task where a product owner emails asking for a status update for a client and you answer from the ticket's status and latest comment. Both run on a practice board, with feedback on every step. The beginner's guide to Jira covers the rest of the everyday basics.