Skip to content
6 changes: 4 additions & 2 deletions docs/USER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -566,6 +566,8 @@ Use this method if OAuth is unavailable (e.g., your organization does not allow

The integration label shows "API Token" and displays the connected site name and URL.

To rotate or replace your API token at any time — or after a token expires — without disconnecting: go to **Settings > Jira Cloud Integration > Auth method** and click **Replace**. Your stored Atlassian email is pre-filled (and can be edited if needed) while your connected site, custom fields, custom scopes, issue key detection setting, and custom issue order remain preserved. Paste the new API token and click **Replace token** — the new token is validated against Jira and encrypted before replacing the old one.

### Issue Key Detection

When issue key detection is enabled, the app scans GitHub issue and PR titles (and PR branch names) for Jira issue key patterns (e.g., `PROJ-123`, `TEAM-42`) after each full data refresh. Matched keys are looked up in Jira and displayed as inline badges on the GitHub item rows showing the issue key, status, and a color indicating status category (blue = new, yellow = in progress, green = done).
Expand All @@ -590,7 +592,7 @@ When Jira is connected, a **Jira** tab appears in the tab bar. It shows all open

**Polling:** Jira issues refresh after each full GitHub poll cycle. There is no hot poll for Jira — issues update every 5 minutes.

If your Jira token expires (OAuth refresh tokens expire after 90 days of inactivity), a notification prompts you to reconnect in Settings.
If your Jira OAuth session or API token expires, the **Jira Assigned** tab remains visible with an **Expired** warning badge while preserving your connected site, custom fields, custom scopes, issue key detection setting, and custom sort order. Both the warning toast and the notification drawer include a clickable **Open Jira settings** link (also shown inside the expired tab callout) that jumps directly to **Settings > Jira Cloud Integration** — and automatically opens the token replacement form for API token users.

### Configuring Custom Fields

Expand Down Expand Up @@ -644,7 +646,7 @@ Local development uses `.dev.vars` (see `.dev.vars.example`). The Jira Cloud Int
### Troubleshooting Jira

**"Reconnect in Settings" notification appears.**
Your OAuth refresh token has expired (90-day inactivity limit) or was revoked. Go to Settings and click **Connect with Jira** to re-authenticate.
Your OAuth refresh token has expired (90-day inactivity limit) or your API token expired or was revoked. Your Jira settings (connected site, custom fields, custom scopes, issue key detection, and custom sort order) remain preserved while the **Jira Assigned** tab displays an **Expired** badge. Click **Open Jira settings** in the toast notification, notification drawer, or expired tab callout to jump straight to **Settings > Jira Cloud Integration** — then click **Reconnect** (for OAuth) or use the inline **Replace** / **Replace token** form (for API tokens, which opens automatically) to re-authenticate.

**OAuth button not visible in Settings.**
`VITE_JIRA_CLIENT_ID` is not set or contains an invalid value. Check your `.env` file or deployment configuration. The API token method is always available regardless of this variable.
Expand Down
26 changes: 21 additions & 5 deletions src/app/components/dashboard/DashboardPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ import {
import { expireToken, user, onAuthCleared, DASHBOARD_STORAGE_KEY, DEP_META_STORAGE_KEY, jiraAuth, setJiraAuth, isJiraAuthenticated, clearJiraAuth } from "../../stores/auth";
import { JiraApiError } from "../../services/jira-client";
import { createJiraClient, mergeCustomFields, jiraJqlForScope } from "../../lib/jira-utils";
import type { JiraIssue } from "../../../shared/jira-types";
import { JIRA_SETTINGS_ACTION, type JiraIssue } from "../../../shared/jira-types";
import { detectAndLookupJiraKeys } from "../../services/jira-keys";
import JiraAssignedTab from "./JiraAssignedTab";
import { updateRelaySnapshot } from "../../lib/mcp-relay";
Expand Down Expand Up @@ -538,7 +538,7 @@ export default function DashboardPage() {
if (err instanceof JiraApiError) {
if (err.status === 401) {
clearJiraAuth();
pushNotification("jira", "Jira session expired — please reconnect in Settings", "warning");
pushNotification("jira", "Jira session expired — please reconnect in Settings", "warning", false, JIRA_SETTINGS_ACTION);
} else if (err.status === 400 && !["assigned", "reported", "watching"].includes(scope)) {
const scopeName = config.jira?.customScopes?.find((s) => s.id === scope)?.name ?? scope;
pushNotification("jira", `Custom scope '${scopeName}' is not supported by your Jira instance. Remove it in Settings.`, "warning");
Expand All @@ -549,6 +549,7 @@ export default function DashboardPage() {
pushNotification("jira", "Jira fetch failed — will retry on next refresh", "warning");
}
} else {
if (err instanceof Error && err.message === "Jira auth cleared during token refresh") return;
pushNotification("jira", "Jira: unexpected error — will retry on next refresh", "warning");
}
} finally {
Expand Down Expand Up @@ -1094,7 +1095,7 @@ export default function DashboardPage() {
isRunVisible(w, { ignoredIds: ignoredRuns, showPrRuns: viewState.showPrRuns, globalFilter: builtinFilter })
).length } : {}),
...(config.enableTracking ? { tracked: viewState.trackedItems.length } : {}),
...(config.jira?.enabled ? (() => {
...(config.jira?.enabled && isJiraAuthenticated() ? (() => {
const f = viewState.tabFilters.jiraAssigned;
return { jiraAssigned: jiraIssues().filter((issue) => {
if (f?.statusCategory !== "all" && issue.fields.status.statusCategory.key !== f?.statusCategory) return false;
Expand Down Expand Up @@ -1137,9 +1138,11 @@ export default function DashboardPage() {
return `${issueTitles}|||${prTitles}`;
});

// Jira key detection runs only when titles change — NOT on every lastRefreshedAt tick.
const jiraAuthed = createMemo(() => isJiraAuthenticated());

// Jira key detection runs only when titles change (or Jira auth transitions false -> true) — NOT on every lastRefreshedAt tick.
// Guards: jira enabled+detection, authenticated, client ready, and titles actually changed.
createEffect(on(titleFingerprint, () => {
createEffect(on([titleFingerprint, jiraAuthed], () => {
if (import.meta.env.DEV) console.info("[jira] key detection guard:", { enabled: config.jira?.enabled, detection: config.jira?.issueKeyDetection, auth: isJiraAuthenticated(), client: !!jiraClient(), refreshed: !!dashboardData.lastRefreshedAt });
if (!config.jira?.enabled || !config.jira?.issueKeyDetection) return;
if (!isJiraAuthenticated()) return;
Expand All @@ -1156,6 +1159,17 @@ export default function DashboardPage() {
}).catch(handleJiraError);
}));

// Re-fetch Jira assigned issues when Jira auth transitions false -> true
createEffect(on(
jiraAuthed,
(authed) => {
if (authed && config.jira?.enabled) {
fetchJiraAssigned().catch(handleJiraError);
}
},
{ defer: true }
));

// Jira assigned issues poll: fires after each GitHub full refresh cycle
createEffect(on(
() => _coordinator()?.lastRefreshAt(),
Expand Down Expand Up @@ -1344,6 +1358,7 @@ export default function DashboardPage() {
enableTracking={config.enableTracking}
enableActions={config.enableActions}
enableJira={!!config.jira?.enabled}
jiraExpired={Boolean(config.jira?.enabled && !isJiraAuthenticated())}
enableDependencies={enableDependencies()}
customTabs={config.customTabs.filter((t) => config.enableActions || t.baseType !== "actions").map((t) => ({ id: t.id, name: t.name, isUnscoped: isTabUnscoped(t) }))}
onAddTab={() => setShowCustomTabModal(true)}
Expand Down Expand Up @@ -1436,6 +1451,7 @@ export default function DashboardPage() {
issues={jiraIssues()}
loading={jiraLoading()}
siteUrl={config.jira?.siteUrl ?? ""}
expired={!isJiraAuthenticated()}
/>
</Match>
<Match when={activeTab() === "actions" && config.enableActions}>
Expand Down
18 changes: 16 additions & 2 deletions src/app/components/dashboard/JiraAssignedTab.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ interface JiraAssignedTabProps {
issues: JiraIssue[];
loading: boolean;
siteUrl: string;
expired?: boolean;
}

const BUILTIN_SCOPE_OPTIONS = [
Expand Down Expand Up @@ -698,7 +699,7 @@ export default function JiraAssignedTab(props: JiraAssignedTabProps) {
</Show>

{/* Jira project groups + locked stubs, or flat custom-ordered list */}
<Show when={isCustomMode() ? customPageItems().length > 0 : pageGroups().length > 0}>
<Show when={!props.expired && (isCustomMode() ? customPageItems().length > 0 : pageGroups().length > 0)}>
<Show
when={isCustomMode()}
fallback={
Expand Down Expand Up @@ -770,8 +771,21 @@ export default function JiraAssignedTab(props: JiraAssignedTabProps) {
</Show>
</Show>

<Show when={props.expired}>
<div class="flex flex-col items-center justify-center gap-3 py-16 text-center px-4" data-testid="jira-expired-state">
<div class="alert alert-warning max-w-md flex flex-col sm:flex-row items-center gap-3">
<span class="text-sm">
Your Jira session or API token has expired. Your Jira settings and custom order are preserved.
</span>
<a href="/settings#jira" class="btn btn-sm btn-neutral shrink-0">
Open Jira settings
</a>
</div>
</div>
</Show>

{/* Empty state — shown when no actual items, whether or not locked stubs appear above */}
<Show when={!props.loading && filtered().length === 0}>
<Show when={!props.expired && !props.loading && filtered().length === 0}>
<div class="flex flex-col items-center justify-center gap-2 py-16 text-base-content/50">
<svg
class="h-10 w-10 opacity-40"
Expand Down
14 changes: 12 additions & 2 deletions src/app/components/layout/TabBar.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ interface TabBarProps {
enableTracking?: boolean;
enableActions?: boolean;
enableJira?: boolean;
jiraExpired?: boolean;
enableDependencies?: boolean;
customTabs?: Array<{ id: string; name: string; isUnscoped?: boolean }>;
onAddTab?: () => void;
Expand Down Expand Up @@ -65,8 +66,17 @@ export default function TabBar(props: TabBarProps) {
<Show when={props.enableJira}>
<Tabs.Trigger value="jiraAssigned" class="tab compact:tab-sm data-[selected]:tab-active">
Jira Assigned
<Show when={props.counts?.jiraAssigned !== undefined}>
<span class="badge badge-sm badge-neutral ml-1">{props.counts?.jiraAssigned}</span>
<Show
when={!props.jiraExpired}
fallback={
<Tooltip content="Jira session expired — click to reconnect in Settings">
<span class="badge badge-sm badge-warning ml-1">Expired</span>
</Tooltip>
}
>
<Show when={props.counts?.jiraAssigned !== undefined}>
<span class="badge badge-sm badge-neutral ml-1">{props.counts?.jiraAssigned}</span>
</Show>
</Show>
</Tabs.Trigger>
</Show>
Expand Down
Loading
Loading