[Feature]: JIRA integration

[mariusleu]

Deployment type

Self-hosted

What do you want and why?

Sync Multica Issues with JIRA issues

Proposed solution (optional)

• Listen to JIRA webhooks
• Configure a mapping between JIRA Status and Multica status
• give context to the agent about JIRA issue number so that can be referenced in commits
• preferrably sync with the JIRA issue number system.

Screenshots / mockups (optional)

No response

[darktempla]

Would be good if this was designed as a pluggable architecture.
Github Issues is another good 1:1 sync

[dhpancor]

This would be good! A lot of us are using external issue tracking services

[iamdempa]

+1 for this feature, hopefully we can implement this.

[jefflunt]

I will try to work on this. I'm new to the project, I'm an external person (not on the multica team), and have looked at CONTRIBUTING.md -- will attempt to submit support for this, and I'll start with submitting a design/plan.

[jefflunt]

There are a few ways to do this, each of which I have some familiarity with, but curious:

• What do people want?
• What will work well with the existing system, or the system's future direction?

Some thoughts below.

---

Proposal for Jira Integration with Bidirectional sync support

Some options

Here drafted are two architectural designs, but I'm open to alternatives/hybrids/something completely different -- mostly collecting feedback at this point.

Option 1: Direct Built-in Core Integration (Bidirectional Sync)

• Concept: Built directly into the Go backend as a first-class integration, following the pattern of the GitHub and Slack/Lark integrations.
• Auth: Support OAuth 2.0 (with a registered Atlassian App) and falls back to Basic Auth (Email + API Token) for self-hosted instances.
• Sync Strategy: Uses Atlassian webhooks for real-time pull syncing. Conflict resolution is handled via a "Last Edit Wins" state check:
  • Add metadata to issues to track jira_last_synced_at locally.
  • Webhook and API updates are only applied if the incoming modification timestamp is newer than our last synced record.
• Custom Status Mapping: Supports mapping custom Jira statuses to Multica standard statuses via a flexible configuration UI, with support for skipping intermediate statuses (e.g. "QA", "PO Approved") that don't map cleanly to Multica.

A note on status mapping

Multica supports only the statuses shown in the baord/swimlane/list view. I think this list is good, and simple. However, Jira is highly configurable and may include the same, more, fewer, or just a totally mismatched set of issue/ticket statuses. As a result, some configuration flexibility may be needed in order to make it possible for someone to use Multica to drive work from Jira. That said, some Jira instances may be configured so strangely that they can't reasonably be made to be compatible with Multica -- but I suppose that's not really a problem to be solved here.

Here's what I had in mind for configurability though -- a JSON file (or similar) that does issue state mapping between the Multica and Jira:

// Jira issue states are the keys, Multica issue state are the values
{
  "jira_to_multica_issue_state_mappings": {
    "To Do": "todo",
    "In Progress": "in_progress",
    "In Review": "in_review",
    "Done": "done"
  },
  "default_status": "todo",
  "skipped_statuses": ["QA", "Staging Approval"]
}

I'm not super clear on whether the bi-directional syncing would work, to be honest, unless there was some background thread to periodically sync. The webhook idea is interesting, but that wouldn't solve the problem for Multica Desktop users, I don't think, because there's no endpoint for an Atlassian webhook to call. Also, self-hosted instances might not be publicly accessible, and therefore couldn't be called either.

Possible technical challenges for bidirectional syncing (conflict resolution)

To avoid infinite update loops (e.g. Multica updates Jira -> Jira emits a webhook -> Multica thinks it's a new Jira edit and updates itself again), we may want something like a "Last Edit Wins" strategy using precise timestamps:

1. Schema Fields to be added somewhere in Multicla:
   • jira_last_synced_at (TIMESTAMP): The exact timestamp when Multica successfully pushed to or pulled from Jira.
   • jira_last_updated_at (TIMESTAMP): The last modified timestamp of the ticket reported directly by Jira.
2. Conflict Resolution Logic:
   • Push Rule (Multica -> Jira): When a user or agent updates an issue in Multica, we fetch the latest ticket metadata from Jira. If Jira's updated timestamp is equal to or older than our jira_last_synced_at, it means no human has modified Jira in the interim. We can safely push our changes to Jira and set jira_last_synced_at = now().
   • Pull Rule (Jira Webhook -> Multica): When a Jira webhook arrives, we inspect its issue.fields.updated timestamp. If it is newer than our jira_last_synced_at (with a small clock-skew tolerance), we process it, apply the mapping, and update the local Multica database, updating both timestamps. If the webhook timestamp matches our last sync, we safely discard the event as a self-echo.

sequenceDiagram
    autonumber
    actor User as Human or Agent
    participant M_Web as Multica Web / App
    participant M_Svr as Multica Go Server
    participant DB as PostgreSQL
    participant Jira as Atlassian Jira API

    %% 1. Config / Connection
    User->>M_Web: Connect Jira & Setup Custom Mapping
    M_Web->>M_Svr: POST /api/workspaces/:id/jira/config
    M_Svr->>DB: Store credentials & status_map JSONB
    M_Svr-->>M_Web: Success

    %% 2. Multica -> Jira Sync
    User->>M_Web: Change issue status to "Done"
    M_Web->>M_Svr: PUT /api/issues/:id (Status: done)
    M_Svr->>DB: Update local issue and record sync intent
    M_Svr->>Jira: PUT /rest/api/3/issue/{key}/transitions (Done)
    Jira-->>M_Svr: Transition Success (updatedAt: T_jira)
    M_Svr->>DB: Update jira_last_synced_at = T_jira

    %% 3. Jira -> Multica Webhook Sync
    Jira->>M_Svr: Webhook: Issue Updated (Status: In Progress, updatedAt: T_jira2)
    M_Svr->>DB: Fetch jira_last_synced_at
    Note over M_Svr,DB: Compare T_jira2 > jira_last_synced_at (Last Edit Wins)
    M_Svr->>DB: Update local issue status via mapped values
    M_Svr->>M_Web: Broadcast event (via WebSockets)

Loading

Option 2: Just use MCP (i.e. no change to Multica's code)

If I understand the per-agent MCP config, it's already possible to add a Jira/Atlassian MCP server to a given agent. This capability means there might not be anything stopping users from using Jira now, but it also means that you have to configure this on a per-issue basis, rather than say on a per-project or per-workspace basis.

---

Or are neither of these a good approach, and if not, why not? Curious to hear what others think.

[dhavli]

I think pull architecture is correct here - Multica in case of Jira integration should NOT be considered source of truth.
Changing anything in Multica should be direct call to Jira via API, webhooks to Multica should not have recursion problem, as long as you don't instruct agents to change stuff in Jira when webhook fires :-)
The way to connect is either OAuth or PAT keys -> Adding OAuth should be fairly straightforward imo, each user would have it's own login via OAuth, and PAT keys would be necessary for agents (they are necessary for the MCP servers already anyway, no change there).

The "view" of how to display the Jira tickets can be done in several ways though, so that one I'm not capable of saying what is "best"...
I would guess you could do eitehr direct Jira display as "embedded site" (so one does not have to switch tabs), or distill the issues and map them to the multica kanban - but this to me sounds like lot of work and problems, so instead being able to interact with jira "directly" inside Multica sounds like a way "I would do" so...

+1 on getting this implemented btw, we are evaluating Multica in my company as our daily driver for agent deployment, but the built-in issue tracker would be just weaking havoc to all our already existing integrations (+ we use Gitlab on top, which is another missing piece)...

[jefflunt]

Thanks for the feedback @dhavli - some more thoughts based on your feedback:

What if:

1. Multica's version of the ticket was only a local cache, and that all changes to Issues in Multica hit the Jira API, as you mention? If I update the status/swimlane of an issue in Multica that would enqueue an update to Jira that would work something like:
   a. first pull latest issue metadata from Jira
   b. see if Multica change conflicts with it (i.e. both Jira and Multica ticket status changed), in this case Jira status wins, Multica-local change is discarded, and issue status is updated to reflect what's in Jira
   c. if Multica change does not conflict with Jira, then push Multica change to Jira via Jira API
2. Should the agent chat on an issue:
   a. remain local to Multica (benefit: only Issue description, title, and status are synced to Jira)
   b. be pushed to Jira as comments on Jira issues (benefit: might allow users that live only in Jira to interact with agents in Multica, in the sense that a comment in Jira might cause a Multica agent to pick up this comment and act on it ... though Jira users are not Multica workspace users, so not sure how that would work)
   c. let this be configurable (benefit: let the Jira integration user decide if they want agent comments pushed to Jira or not, via a toggle)
   d. something else?
3. Remove webhook support (i.e. don't expect Jira to call over to Multica), and instead have Multica trigger a refresh of a Jira issue when the user views/interacts with the Multica issue.
   a. In this way the API traffic to Jira remains scoped to just the issues users are interacting with. In this model, I think viewing a board/list/swimlane might also trigger title/description/status updates of issues that are visible filtered in Multica
   b. perhaps this polling at a board/list/swimlane level is capped to no more than every 5 minutes or so

Webhooks

I guess webhook support (Jira calling back into Multica) could be setup, assuming the Multica instance was reachable from Jira cloud or Jira enterprise hosting. However, we might might need a fallback of Multica updating Jira issues in the case where your Multica instance isn't network reachable from your Jira instance.

Authorization / connection:

+1 to OAuth / PAT.

Multica as daily driver

... we are evaluating Multica in my company as our daily driver for agent deployment, but the built-in issue tracker would be just weaking havoc to all our already existing integrations (+ we use Gitlab on top, which is another missing piece)...

I have similar challenges:

1. I'd like to be able to plug Multica into Jira. I have a personal Jira instance I pay for that I'd test it with. If something good results here, then I would also consider plugging it into work Jira.
2. When Jira is plugged into a Multica instance, should you even be able to create issues in Multica? If so, they'd have to sync to Jira, I presume (thoughts?)

[jefflunt]

Going to keep an eye on #4490 - ideas around a plugin system.

[jefflunt]

Going to hold off going much further with any technical recommendations until there's more information on the plugin concept. Agree with @darktempla that a plugin seems like a good way to approach this, but curious to see what the maintainers think.

High-level:

• Want to support bi-directional syncing w/Jira as the source of truth if there's ever a conflict
• Want to leverage whatever plug-in system the maintainers come up with
• I'm hoping the plugin system will allow extensibility to the Issues system, which would allow support for more than Jira eventually (maybe GitHub issues, and others as well)

[zerox9dev]

Opened #5919 with a first implementation.

Approach: built on the existing VCS-integration pattern (per-workspace API-token, secretbox-encrypted). It supports both ingest paths so it doesn't require Jira admin:

• Pull — "Sync now" + optional per-connection JQL (default assignee = currentUser()) via the Jira REST API. No webhook/admin/tunnel.
• Push — inbound webhook verified by a per-connection secret (Jira Cloud doesn't sign webhooks).

Includes schema, connection CRUD, the settings UI (Settings → Integrations → Jira), i18n, and tests. Verified end-to-end against a real Jira Cloud site.

One decision I'd value a steer on before the follow-ups: auth model — v1 uses a per-workspace Jira Cloud API token (simplest for self-hosters, matches VCS); Atlassian Connect/OAuth would be cleaner but needs a hosted app. OK to keep API-token for v1?

Deliberately left for follow-ups: outbound status/comment sync + status mapping, agent-context injection of the Jira key, and a scheduled periodic poll.