How to configure Jira for Mermix

Mermix is only as good as the data it reads from Jira. This guide covers what to connect and which fields to fill in so Mermix can place work on the calendar automatically — instead of dropping everything into the backlog for you to schedule by hand.

Connecting Jira

Mermix connects to Jira Cloud using Atlassian's official OAuth flow. In Portfolios → Workspace (or the setup wizard on first login), click Connect with Atlassian, log in, and approve access. Mermix never sees or stores your Atlassian password.

A workspace stays with the Jira site it is first connected to. To disconnect Jira from your workspace, email hello@mermix.io from an Admin's address and we'll do it for you.

One person — a Jira administrator of your site — connects Jira for the whole workspace. Everyone else just uses Mermix. Before connecting, go through Before you start: who should connect, the Jira permissions Mermix needs, and settings that can block apps.

Choosing what to sync

Projects. Pick the Jira projects you actually plan in. The setup wizard keeps this to three to get you started quickly; add or remove projects any time in Portfolios → All projects (Admins), and group them into Portfolios. There's no limit on the number of projects on any plan.

Issue types. Choose which issue types Mermix should plan — Story, Bug, and Task are the usual set and are selected by default. An Admin changes the list later on Portfolios → All projects → Issue types. A few notes:

• Epics are treated as containers, not scheduled work. Mermix uses them to group and label issues, never as a bar on the calendar.
• Sub-tasks are available but off by default — turn them on only if you schedule at sub-task granularity.

Sync from. When you add a project, you choose how far back Mermix imports its completed work and logged time: 3, 6 or 9 months, 1 to 4 years, or a specific date. Six months is selected for you. How far back you can go depends on your plan — Starter 1 year, Team 2 years, Enterprise 4 years. Open work is always brought in, whatever you choose. You can see each project's date in Portfolios → All projects → Sync from. To sync from an earlier date later, use Sync from… on that project; nothing already imported changes. Nothing in Jira is changed either way.

The four signals that put work on the calendar

For every issue, Mermix reads four things from Jira. The more of them you fill in, the smarter the placement:

The single biggest thing you can do: assign issues and give them an estimate. An assigned issue with an estimate always lands on the calendar, sequenced after that person's other work — even with no dates at all. The exact rules are in How Mermix schedules your Jira issues.

The start-date field

The Due date in Jira is a standard field. For the start, Mermix uses the Start date field built into Jira, which Jira Software sites have and usually show on every project's screens. The calendar and timeline in Jira read the same field, so the dates you push from Mermix show there too. During onboarding Mermix looks for it by name.

Mermix never creates a field in your Jira. If your site has none, the wizard tells you, and a Jira administrator can restore it from the trash (Jira settings → Fields) or show it on your projects: the field scheme of each company-managed project, or the work type in a team-managed space. Until a project has the field on its screens, Mermix pushes everything except the start date and tells you why.

If your teams already keep their start dates in another date field, for example one your dashboards or Jira Plans read, you can link that field instead in Portfolios → Workspace → Jira fields. Know the trade-off first: the calendar and timeline in Jira read only the Start date field, so the start dates Mermix pushes will not show there; work appears on the Jira calendar on its due date only. Mermix's own calendar is not affected. Jira Plans (Premium) can be set to read a custom start-date field. The same section lets advanced users map their own fields for actual start/end dates — otherwise Mermix derives progress automatically from each issue's Jira status history, so you don't have to maintain anything extra.

Getting the most out of Mermix

A quick checklist that pays off immediately:

• Assign your issues. Unassigned work can't be placed on anyone's calendar.
• Add estimates. Even a rough Original estimate lets Mermix size and sequence work.
• Set due dates where they matter — Mermix schedules backwards from them so deadlines are respected.
• Use sprints. Mermix reads Jira sprints, shows sprint badges on the backlog, and can draw sprint boundaries on the calendar.
• Set each person's country in Portfolios → All people (the ⋯ menu on their row → Edit name, email, country) so Mermix skips the right public holidays when it calculates capacity and working days.

Keeping Jira and Mermix in sync

Syncing is manual and on-demand — click Pull from Jira whenever you want the latest. Mermix shows you exactly what changed before anything is applied, and your local planning tweaks are never silently overwritten. When you want your Mermix changes to flow the other way, see Pushing your plan back to Jira.

Completed issues are handled quietly: work that's Done in Jira is marked complete in Mermix and never clutters your active plan. This happens as soon as the Pull from Jira window has read from Jira, even if you close it without importing anything:

• a task on the calendar that is Done in Jira is marked 100% complete (its dates stay as they are);
• a backlog item that is Done in Jira is removed from the backlog;
• completed work by people on your team is added as history, so reports can count it.

Only open work waits for you to tick it and press Import.