Getting Started — MR Dashboard for GitLab

Setup

1. Install the app from the Atlassian Marketplace.
2. As a project admin, open a Jira project and go to Project settings → Apps → MR Dashboard to configure its GitLab connection. (The dashboard's own header also has a settings shortcut that jumps you straight there.)
3. Fill in:
   • GitLab URL — https://gitlab.com, or your self-hosted instance's base URL.
   • Access token — a token with the read_api scope (the app never writes to GitLab, so no other scope is needed). See the Security Policy for the recommended token type.
   • Source — pick Project or Group, then choose it from the searchable list (type to filter, or just focus the field to see your most recently active ones).
4. Test connection, then Save.
5. Open MR Dashboard from the project sidebar — it loads automatically once settings are saved.

Each Jira project's connection is independent: every project has its own GitLab URL, source, and token, so different projects can point at entirely different GitLab hosts (e.g. one at gitlab.com, another at a self-hosted instance) or different groups/projects on the same host. Repeat this setup once per Jira project that should show a dashboard.

Statuses explained

Every open merge request past the stale threshold gets one of three diagnoses, shown as a colored badge throughout the dashboard.

Stale

Any open MR older than the 'Stale after' threshold. Every stale MR gets one of the three diagnoses below.

Old

Stale, but with an ordinary quiet history: fewer than 5 comments and not silent long enough to be Forgotten. Nothing is wrong except the time it's taking.

Forgotten

At most 1 comment AND no activity longer than the silence threshold — nobody is looking at it. Any new activity — a comment, commit, reassignment, or any other update — moves it back to Old.

Churning

5 or more comments while still unmerged — review and rework loops without progress. This status doesn't clear with activity: the discussion history stays.

The comment counts above (5 for Churning, 1 for Forgotten) are defaults; configurable via the gear on the Summary card.

Both age/silence thresholds are configurable in the dashboard's filter bar: MR is Stale after (days) sets the age behind Stale/Old, and Mark Forgotten after (days of silence) sets the silence window behind Forgotten. Adjust them and click Apply filters to recompute every status.

Troubleshooting

• If the dashboard looks empty or a save fails, open Settings and run Connection diagnostics — it checks your saved credentials against GitLab step by step (project/group access, subgroups, projects, merge requests, GitLab version) and reports exactly which check failed.
• Self-hosted GitLab must be publicly reachable over HTTPS. The app's backend runs on Atlassian's Forge infrastructure, not inside your company network — if your GitLab instance only resolves on an internal VPN/intranet, Forge cannot reach it. A reverse proxy with a public HTTPS address (optionally IP-restricted to Atlassian's egress ranges) is the usual fix.
• Two similar-looking yellow banners mean different things. "GitLab rate limit reached — some data may be incomplete. Try again in a minute." means GitLab itself rejected some requests; retrying shortly (via the Retry button in the banner) usually clears it. "Large group — showing partial data. Narrow the date range or use a subgroup." means the dashboard's own per-load time budget ran out before every project in the group was queried — retrying immediately won't help by itself; narrowing the date range or switching to a subgroup will (see the FAQ above). The two can also appear together on the same load. Either way, whatever data the dashboard already collected stays on screen underneath the banner — neither one blocks the dashboard the way "Not connected to GitLab" or "GitLab token is invalid or expired" do.

FAQ

What data does the app store?

Just your connection settings (GitLab URL, project/group ID) and the access token you enter — the token is stored in Forge Secret Storage, encrypted at rest and never exposed to the browser. Merge request statistics themselves are cached for up to 2 minutes in Forge's key-value store purely to avoid re-querying GitLab on every reload — nothing is retained beyond that window. See the Privacy Policy for the full details.

What GitLab versions are supported?

gitlab.com (SaaS) and self-managed GitLab CE/EE — anything that exposes the standard REST API v4. The app is actively validated against current GitLab releases, but since it only relies on long-stable v4 endpoints (projects, groups, merge requests, members, notes), reasonably recent self-managed versions work as well.

I added (or deleted) comments, pressed Refresh, but the comment count and status look outdated. Why?

The dashboard reads merge requests from GitLab's list API, whose comment counter (user_notes_count) is cached on GitLab's side and can lag behind reality by several minutes after comments are added or deleted. The per-MR timeline loads the actual comments live, so it may briefly disagree with the counter. This resolves on GitLab's side — usually within minutes, or after the next update to the MR. Press Refresh afterwards and statuses will recalculate. The Refresh button clears the dashboard's own 2-minute cache, but it cannot speed up GitLab's internal counter.

I upgraded and now it says "Not connected to GitLab" — where did my settings go?

Nothing was lost. Starting in version 3.0.0, each Jira project has its own independent GitLab connection instead of one connection shared across the whole site. If a connection was configured before the upgrade, that data is preserved and offered as a pre-filled draft the first time you open a project's settings page — but it only becomes active for that project once you press Save there. Every other project that never had a connection of its own naturally shows "Not connected" until someone configures it (which can now be a completely different GitLab URL/project per Jira project — see Setup above). Open Project settings → Apps → MR Dashboard, confirm the pre-filled values (or enter new ones), and Save.

Why does it say "Large group — showing partial data"?

Every group-mode load has a fixed time budget: the dashboard queries every project under the group for merge requests and members, and if there are enough projects that it can't finish within that budget, it returns whatever it already collected instead of failing outright — flagged with this banner. (This is a different condition from the separate "GitLab rate limit reached" banner — see Troubleshooting below for the distinction.) The most reliable fix is pointing the connection at a subgroup instead of the whole top-level group, if your team structure allows it: fewer projects to enumerate per load means the fetch reliably finishes in time. Narrowing the date range also helps, since GitLab has less data to return per project.