HOW TO

Your team is tracking bugs in Jira. Decisions are being made in Confluence. And somewhere between the two, important context is getting lost.

Sound familiar?

You’re not alone. Over 65,000 teams globally use Jira to manage issues, while Confluence serves as the central wiki and documentation hub for more than 75,000 organizations — many of them the exact same companies. Yet most teams still copy-paste issue lists manually, update status spreadsheets by hand, and wonder why their project pages always feel out of date.

The fix is simpler than you think: add Jira filters directly to your Confluence pages.

When you embed a Jira filter into Confluence, your pages display live, real-time issue data — no manual updates, no stale screenshots. Decisions get made on accurate information. Meetings become shorter. And your team stops playing telephone between tools.

This guide walks you through exactly how to do it, step by step.

What Is a Jira Filter (And Why It Matters in Confluence)

A Jira filter is a saved search query. It pulls a specific set of issues based on criteria you define — project, status, assignee, label, priority, sprint, or any custom field you’ve set up.

Think of it as a smart, dynamic list. Instead of manually curating which issues appear somewhere, the filter does the work automatically. Every time someone views the page, the data refreshes to reflect the current state of your Jira board.

When you embed that filter into Confluence:

• Project status pages stay accurate without anyone updating them
• Sprint review meetings have a live source of truth
• Stakeholders can see issue progress without needing Jira access
• Onboarding documents can reference active tasks in context

According to Atlassian, teams that integrate their tools and reduce context-switching save an average of 2+ hours per person per week. Across a team of ten, that’s 20 hours recovered every single week — without changing how anyone works.

What You Need Before You Start

Before embedding a Jira filter into a Confluence page, make sure you have:

A connected Atlassian account. Jira and Confluence need to be linked under the same Atlassian organization. If you’re on Atlassian Cloud, this is typically handled automatically. If you’re on separate instances, your admin may need to configure the application link first.

An existing Jira filter. You’ll need a saved filter in Jira before you can reference it in Confluence. We’ll cover how to create one below.

Edit access to the Confluence page. You need at least “Can Edit” permissions on the target page.

The Jira macro enabled in Confluence. On most Atlassian Cloud setups, this is on by default. If you’re on a self-managed (Server/Data Center) instance, check with your admin that the Jira macro is installed and active.

How to Create and Save a Jira Filter

If you already have a saved Jira filter, skip ahead to the next section. If not, here’s how to create one in under two minutes.

Create the Filter in Jira

Log into Jira and navigate to Issues in the top navigation bar, then select Search for Issues (or press the keyboard shortcut G + I).

Use the search bar to build your query. You can use the basic search mode for simple filters (dropdown selectors for project, type, status) or switch to JQL (Jira Query Language) for more precise control.

Example JQL queries to get you started:

• All open bugs in a project: project = “YOUR_PROJECT” AND issuetype = Bug AND status != Done
  
  
• Issues assigned to your team this sprint: project = “YOUR_PROJECT” AND sprint in openSprints() AND assignee in membersOf(“your-team”)
  
  
• High-priority unresolved issues: priority in (High, Highest) AND resolution = Unresolved ORDER BY priority DESC
  
  

Once your query returns the right results, click Save As (usually in the upper right of the search results page), give your filter a clear name, and save it.

Share the Filter (Important Step)

For the filter to work in Confluence — especially for teammates who view the page — you need to make sure the filter is shared.

Click Details next to your saved filter, then set the Permissions to either your specific team members or to “All Logged-In Users” depending on your use case.

Research shows that 56% of project failures are linked to poor communication and information silos. Sharing filters publicly within your organization closes that gap — everyone sees the same live data.

How to Add a Jira Filter to a Confluence Page

Now for the main event.

Open the Confluence Page Editor

Navigate to the Confluence page where you want to display the Jira filter. Click Edit (the pencil icon) to open the page editor.

Insert the Jira Issues Macro

In the editor, place your cursor where you want the Jira issue list to appear. Then do one of the following:

• Type /jira and select “Jira Issues” from the dropdown that appears
• Click the + (Insert) button in the toolbar and search for “Jira Issues”
• Use the keyboard shortcut { and type “jira” to browse macros

This opens the Jira Issues macro configuration panel.

Configure the Macro

Inside the macro settings, you have three main options for what to display:

Option 1 — Display by Saved Filter (Recommended)

In the macro panel, look for the option that says “Search by filter” or a similar label depending on your Confluence version. Enter the name or ID of your saved filter.

The macro will preview a list of matching issues inline. You can see exactly what will appear on the page before saving.

Option 2 — Display by JQL Query

If you prefer not to save a filter in Jira first, you can paste a JQL query directly into the macro panel. Confluence will run the query and display results dynamically.

This is useful for quick one-off embeds, but saved filters are easier to update and maintain over time — especially if multiple pages reference the same criteria.

Option 3 — Display a Single Issue

Paste a specific Jira issue key (e.g., PROJ-123) to display just that issue in a compact card format. Useful for linking decisions in meeting notes to the exact issue they reference.

Choose Which Columns to Display

Once your filter or query is entered, you can customize which columns appear in the table on your Confluence page. Common choices include:

• Issue key
• Summary
• Status
• Assignee
• Priority
• Due date
• Labels

A 2023 survey by Project Management Institute found that 71% of high-performing project teams cite clear visibility into task ownership and status as a key driver of success. Choosing the right columns makes the difference between a useful status page and a confusing data dump.

Keep it focused. Three to five columns is usually enough. More than that and the table becomes hard to scan.

Set the Maximum Number of Issues to Display

You can control how many issues appear. The default is typically 20. For status update pages, 10–15 is often cleaner. For full backlog views, you might want 50 or more — though very long tables can slow down page load and overwhelm readers.

Save the Macro and Publish the Page

Click Insert or Save in the macro settings panel to close it and return to the editor. You’ll see a live preview of the Jira issues table directly on your page.

When the page looks right, click Publish (or Update if editing an existing page). Your Confluence page now displays a live Jira filter — automatically refreshed every time someone loads it.

Using the Jira Chart Macro for Visual Data

Beyond plain issue tables, Confluence also supports the Jira Chart macro — a way to visualize filter results as charts directly on your page.

How to add it:

In the editor, type /jira chart or search for “Jira Chart” in the macro browser. Connect it to a saved filter and choose your chart type:

• Pie chart — great for showing issue distribution by status, type, or priority
• Created vs. Resolved chart — useful for tracking whether your team is resolving issues faster than they’re being created
• Two-dimensional grid — shows issue counts across two fields, like type vs. priority

Why this matters: Atlassian data shows that teams using visual project tracking close issues 30% faster than those relying on list-only views. Seeing a pie chart of open vs. closed bugs communicates status in two seconds. Reading a table of 50 issues takes two minutes.

Use charts at the top of project overview pages, and tables lower down for the detail.

Practical Use Cases Worth Stealing

Here’s where embedding Jira filters in Confluence delivers the most value.

Sprint Planning Pages Embed a filter showing all backlog items tagged for the upcoming sprint. When the planning meeting starts, everyone’s looking at the same live list — no “which version are you looking at?” confusion.

Bug Triage Dashboards Create a Confluence page dedicated to open bugs, filtered by priority. Stakeholders who don’t have Jira access can check the dashboard at any time without needing a login or a status update email.

Release Notes and Release Tracking Embed a filter showing all issues completed in the current release version. Update the filter as the sprint closes and the release notes page updates automatically.

Retrospective Prep Pages Before your retrospective, embed a filter showing all resolved issues from the sprint. Teams can review what shipped without manually compiling a list.

Onboarding Wikis For new team members, a Confluence page with embedded Jira filters gives them a live view of what the team is currently working on — much more useful than a static description.

A study by Gallup found that employees who feel informed about their team’s work are 21% more productive. Confluence pages powered by Jira filters make that information visible to everyone, automatically.

Common Errors and How to Fix Them

“The filter cannot be found or you don’t have permission to view it.” The filter is either private or hasn’t been shared. Go back to Jira, open the filter settings, and update sharing permissions to include the relevant users or groups.

The table shows but all fields appear blank. This usually means the column names in the macro don’t match the field names in your Jira instance. Open the macro settings and reselect the columns from the available field list.

The Jira macro doesn’t appear in the Confluence insert menu. On cloud, make sure Jira and Confluence are connected under the same Atlassian organization. On Server/Data Center, an admin needs to set up the Application Link between the two products under General Configuration → Application Links.

The filter works in Jira but shows no results in Confluence. Double-check that the JQL query is valid and that the filter has been shared. Also verify that the issues in the filter haven’t all moved to a status that’s excluded by your query.

Page loads slowly when the macro is present. Large filters (200+ issues) can slow Confluence page rendering. Limit the macro to 20–50 issues and consider paginating across multiple pages or using the chart macro instead of a full table.

Tips to Get More Out of Jira Filters in Confluence

Name your filters clearly. “Sprint 14 – Open Bugs – Priority High” is infinitely more useful than “My Filter 3” when someone else needs to update the page six months later.

Use Confluence page templates. If your team regularly creates sprint review pages, project status pages, or release trackers, build a Confluence template with the Jira macros pre-configured. Just update the filter reference for each new page.

Pin filter-powered pages in Confluence spaces. If a dashboard page is useful, make it easy to find. Pin it to your space sidebar so it’s always one click away.

Audit your filters quarterly. Jira filters that reference deleted projects or closed sprints can throw errors. A quick quarterly review keeps your Confluence pages clean.

Combine multiple macros on one page. A strong project status page might include a Jira Chart macro at the top (showing issue breakdown by status) and a Jira Issues table below (showing the actual open issues). Together they give both the summary and the detail in one place.

Conclusion

Adding Jira filters to Confluence pages is one of the highest-leverage things you can do to close the gap between where work gets done and where decisions get made.

The setup takes about five minutes once you have a saved filter. But the payoff — accurate project pages, live status dashboards, faster meetings, and a team that actually trusts the documentation — compounds over months and years.

Here’s your quick action plan:

1. Create and save a Jira filter for the most important view your team needs right now
2. Share the filter with the right permissions
3. Open the relevant Confluence page, embed the Jira Issues macro, and publish
4. Build a template so every future project page starts with the same structure

The teams that win aren’t the ones with the best tools. They’re the ones who actually connect those tools together and use them consistently.

Start with one page. The rest follows naturally.