Documentation

Customer documentation

Everything Slack workspace admins and Jira project admins need to install, configure, and run Threadmaker. Power users in mapped channels can skim the scenarios + shortcut + mentions sections. If you can't find an answer here, email support@cinderlab.io.

Install in 5 steps

1. Add Threadmaker to Slack. Click the Add to Slack button on threadmaker.dev or your Slack App Directory entry and authorize the workspace. After OAuth completes you'll see your connection token — a UUID that pairs the Slack app with its Jira counterpart. Copy it (we also DM it to you).
2. Install the Forge plugin from the Atlassian Marketplace. In Jira admin, open Apps → Threadmaker (Global), paste the connection token from step 1 plus the App URL (https://threadmaker.dev), and save.
3. Enable a Jira project. Open Project settings → Threadmaker and toggle Enabled on. The default templates are sensible — you'll customise them later.
4. Pair a Slack channel with that project. In Slack, run /jira-map in the channel you want to use. The modal shows your Jira projects; pick one and confirm.
5. Try it. Comment on a Jira issue in the paired project. Threadmaker creates a thread in the Slack channel and posts the comment as a reply. Reply in the thread — the message lands as a Jira comment within seconds.

That's it. Everything from here is configuration, edge cases, and optional features.

Three ways teams use Threadmaker

How the sync works

Three ideas drive every feature:

• One thread per ticket. Each Jira issue gets one anchor message — a thread root in its mapped channel. All Jira-side activity for that ticket — comments, attachments, status updates — appears as replies in that thread. The conversation lives in one place.
• Bidirectional, with attribution. Slack replies become Jira comments; Jira comments become Slack replies. Both sides carry author attribution ([Alice via Slack] ... in Jira; "Alice (Jira)" in Slack) — Threadmaker never silently "speaks for" a real user.
• Per-project opt-in. Every behaviour — enabled at all, sync edits, sync attachments, sync reactions, allow Slack→Jira issue creation, live anchor updates — is a Jira project-admin decision in Project settings → Threadmaker. Workspace admins on the Slack side pair channels but don't override a project-admin's "off". Defaults are conservative.

Slash commands (admin)

Pair a channel with a project — /jira-map

Tell Threadmaker which Jira project a channel belongs to. Run inside the channel you want to pair.

• /jira-map (no args) — opens a modal with a dropdown of your Jira projects. Pick one and confirm. Best for discoverability.
• /jira-map PROJ — power-user shortcut. Validates the project key and binds it to the current channel. PROJ must be uppercase letters/digits.
• /jira-map off — unbind the current channel. Existing anchor messages stay in place; new Jira activity stops syncing.

Create issues from Slack — /jira-create

Open a Jira create-issue modal without leaving the channel. OFF by default per project; a Jira project admin opts in via Project settings → Threadmaker → Allow Slack to create Jira issues. When on, anyone in the channel can run the command.

Running /jira-create opens a modal with project, issue type, summary, and description fields. Issue type defaults to the project's first standard type (Task/Story/Bug/Epic for Software; Incident/Service Request/Problem for JSM). Required custom fields surface as additional inputs. Submit to create the issue and post a confirmation message linking to it.

Inspect what's been syncing — /jira-audit

Show recent sync events for the project paired to the current channel: timestamp, direction (Slack→Jira or Jira→Slack), action (create/edit/delete/transition), issue key, actor, and status (success/failed).

• /jira-audit — last 20 events.
• /jira-audit 50 — last 50 events (max 200).

Choose where alerts go — /jira-alerts

Pick the Slack channel that receives failure alerts when a sync attempt fails permanently (5 retries exhausted). Without an alerts channel, failures are silent — the audit log captures them but no human gets pinged.

• /jira-alerts (no args) — opens a channel-picker modal.
• /jira-alerts CXXXXXXX — direct channel-ID form.
• /jira-alerts off — clear the alerts channel.

Most admins prefer a dedicated #threadmaker-alerts channel so the bot can post freely. Invite the bot first.

Forward any message to Jira

Use case: a side conversation in another channel or thread is relevant to a live ticket. Right-click any message (or hover → three-dots menu) and pick Send to Jira. Threadmaker posts that message as a comment on the matching Jira ticket — useful for forwarding a discussion that started elsewhere into the canonical ticket thread.

• Available in any channel where the bot is installed; if the channel isn't paired to a project, you'll get a prompt to pick which Jira issue to post to.
• Carries author attribution ([Alice via Slack — sent from #other-channel]).
• Attachments on the original message forward subject to the attachment limits.

Live status in the thread title

The first time a Jira ticket has activity in a paired channel, Threadmaker posts an anchor message — the thread root for all subsequent activity on that ticket. Default format:

WEB-1234 — Add export to PDF
Type: Story · Status: In Progress · Priority: High · Assignee: Alice

When type, status, priority, issuetype, summary, or assignee change in Jira, your anchor updates in place to reflect the new value — the thread title in Slack always shows the current state. Updates edit the existing message silently; they don't create new notifications.

Per-project toggle: live updates can be disabled in Project settings → Threadmaker → Sync anchor field updates (default ON). When OFF, the anchor posts once at thread creation and never updates. Useful if your team prefers immutable thread roots.

The anchor format is a configurable template (live preview in the settings page). Available variables:

• {{issue.key}} — e.g. WEB-1234
• {{issue.summary}} — one-line title
• {{issue.url}} — full Jira URL (used in <{{issue.url}}|{{issue.key}}> for clickable links)
• {{issue.status}}, {{issue.type}}, {{issue.priority}}, {{issue.assignee}}
• {{issue.reporter}}

The template engine refuses to save without {{issue.key}} and {{issue.url}} — they're required for the anchor to be discoverable on retry.

Edits and deletes flow both ways

If a Slack reply or a Jira comment is edited, the corresponding message on the other side updates within seconds. Same for deletes — deleting a Slack reply removes the matching Jira comment, and vice versa.

Per-project toggle: Project settings → Threadmaker → Sync edits and deletes (default ON). Turn off if your team needs Jira comments to be immutable for compliance or audit reasons; Slack-side edits will then be ignored, and the original synced version stays in Jira.

Reactions become Jira signals

OFF by default. A Jira project admin opts in via Project settings → Threadmaker → Sync Slack reactions to Jira.

When on, reacting on a synced message in Slack creates a lightweight mini-comment on the matching Jira comment, e.g.

👀 Alice reacted with :eyes: in Slack

Removing the reaction removes the mini-comment. Reactions on the anchor message itself create a mini-comment on the Jira issue (not on a specific comment).

Customisable templates and emoji-to-transition mapping live in the same project-settings page. Examples:

• Map specific emoji to specific Jira transitions instead of mini-comments — e.g. :white_check_mark: moves the issue to Done. Configure in Reaction transitions as a JSON map ({ "white_check_mark": "Done" }, up to 20 entries).
• Customise the mini-comment body via {{reaction.emoji}}, {{reaction.actor}}, {{reaction.targetUrl}} variables.

Limitation: sync is one-way (Slack → Jira). Native Jira comment reactions aren't yet exposed via Atlassian's public API (JRACLOUD-78153); when that ships, the reverse direction is a 1–2 day update.

@-mentions cross the boundary

Slack @alice in a synced message becomes a real clickable Jira mention if Alice's Slack email matches her Jira account email — and vice versa. The mention pings the right person on the destination side.

Three-tier graceful fallback (no admin action required):

1. Match. Emails align on both sides → real ping with a clickable link.
2. Display-name fallback. Email aligns on one side but not the other → the message renders as @DisplayName plain text (no ping, but readable).
3. Literal fallback. No email available → the message renders the original ID (@U12345 in Jira or @accountid in Slack).

Lookups are cached for 24 hours per workspace. Up to 10 distinct mentions resolve per comment (Cloudflare subrequest cap).

Files, screenshots, inline images

File attachments sync in both directions:

• Slack → Jira: files attached to a Slack reply land as attachments on the Jira comment.
• Jira → Slack: files attached to a Jira comment land as separate file-share messages in the Slack thread, paired with the parent comment.

Inline images. When you attach an image (PNG, JPEG, JPG, GIF, WebP) to a Jira comment, it renders inline in the Jira comment body — not just in the Attachments tab. SVG and other formats aren't inlined for security reasons but still appear as attachments.

Why the cap? Threadmaker forwards file bytes through the Cloudflare Workers + Atlassian Forge proxies, both of which have fixed body-size budgets. The 5×2 MB shape covers the vast majority of triage attachments (screenshots, log snippets, PDFs, small CSVs). For large files (videos, log dumps, full database dumps), upload to your team's storage system and paste a link in the comment.

Per-project configuration

Every behaviour is per-project. Open Project settings → Threadmaker in Jira to configure:

Saving any setting pushes the change to the Threadmaker backend within seconds. Workspace admins on the Slack side don't need to do anything — the new behaviour applies to the next event.

App Home tab in Slack

Open Threadmaker from the Slack sidebar (or Apps → Threadmaker) to see the App Home tab:

• Setup wizard — the same 5 steps from Install in 5 steps, with progress indicators based on what you've already configured.
• Connection token — copy or rotate. Rotating invalidates every previous Forge ↔ Worker connection; you must re-paste the new token in Jira admin afterwards. Use only if you suspect the previous token leaked.
• Failure alerts channel — current setting + a button to change.
• License status — Atlassian Marketplace billing state (active / trial / lapsed). When a paying license lapses, Threadmaker enters a 7-day grace period during which sync continues; after that, sync pauses until the license is reactivated.

Glossary

Anchor message

The thread root posted by Threadmaker when the first Jira activity hits a mapped channel. Displays the issue key, summary, type, status, priority, and assignee. All synced comments become replies to this message. Updated in place when Jira fields change.

Mapped channel (or "paired channel")

A Slack channel linked to a Jira project via /jira-map. Issues from that project create anchor messages in that channel. One channel = one project.

Connection token

A UUID generated at OAuth that pairs a Slack workspace with its Forge plugin. The Slack workspace admin pastes this token into Apps → Threadmaker (Global) in Jira admin. Rotatable from the App Home tab.

Marker

An invisible token (e.g. [sync:T08LX:C012:1700000000.000000]) embedded at the end of synced messages. Lets Threadmaker recover from partial failures by finding the right Jira comment on retry. The {{tm.marker}} template variable inserts it.

Live updates

The behaviour where an anchor message in Slack edits itself when the underlying Jira issue's status, type, priority, or assignee changes. Toggle in Project settings → Sync anchor field updates.

Pricing tiers

Threadmaker is free for 1–10 users. Paid tiers (Team / Business / Enterprise) bill through the Atlassian Marketplace by Jira user count; no feature gates — every tier gets the full feature set (edit sync, reactions, /jira-create, custom templates, live anchors). The Slack app itself is always free; Atlassian handles the billing.

See threadmaker.dev pricing for tier details, annual discounts, and the 7-day trial.

Roadmap and current constraints

Coming soon

• Slack Enterprise Grid support (Q3 2026) — v1.x targets single workspaces. If your company runs Grid and wants to pilot, email contact@cinderlab.io for early access.
• Bidirectional reaction sync (gated on Atlassian JRACLOUD-78153) — Atlassian doesn't yet expose comment reactions via public API. When that ships, the reverse direction is a 1–2 day update.

Architecture constraints (not priorities)

• Attachment cap: 5 files × 2 MB per comment (see attachments). Larger files belong in your team's storage; paste a link in the comment.
• Mention email matching: requires that a person's Slack email matches their Jira account email. SSO setups where the two differ fall back to display-name text rendering — readable but no ping.
• Custom-field validation in /jira-create: we surface required built-in fields and most custom-field types (priority, labels, components, single-select). Highly custom types (cascade selects, scripted defaults) may not validate cleanly through the modal — fall back to creating the issue in Jira directly.
• Sync latency: typical 1–5 seconds end-to-end. Slower under Atlassian Forge cold-start (the first event after a quiet period can take 10–30 seconds). Operations are durable — a retry queue catches anything that fails on the first attempt.

Disable or uninstall cleanly

You can back out of Threadmaker without losing data. Three levels:

• Disable for one project. Open Project settings → Threadmaker and toggle Enabled OFF. Existing anchor messages stay in the channel; new Jira activity stops syncing. Jira comments and attachments are not deleted.
• Uninstall the Slack app. Go to Apps → Threadmaker in Slack, click Uninstall App. The Slack-side sync stops; Jira is unaffected. Threadmaker auto-purges your workspace's data from our backend within 30 days, per Privacy Policy §6.
• Uninstall the Forge plugin. Go to Apps → Threadmaker (Global) in Jira admin, click Uninstall. Forge-side configuration is removed. The Slack app continues to work; the App Home tab will show "not connected".

For an immediate full-data wipe (GDPR data-subject request), email contact@cinderlab.io with subject "Data deletion request" — we'll purge all workspace data within 30 days.

Troubleshooting

Comments aren't syncing

1. Run /jira-audit in the channel — it shows the last 20 sync events including failures. Check for any "failed" rows.
2. Confirm the channel is paired: re-run /jira-map PROJ and look for the "channel paired to PROJ" confirmation.
3. Confirm the project is enabled in Project settings → Threadmaker.
4. Confirm the bot is invited to the channel (/invite @Threadmaker) — Slack bots only receive events from channels they're a member of, both public and private.
5. Check the App Home tab for a license-paused banner. A lapsed Atlassian Marketplace subscription pauses sync after a 7-day grace period.

The anchor message shows the wrong status

The anchor was likely created before live updates landed (v1.16+), or live updates are disabled in Project settings → Sync anchor field updates. Manually re-run any operation on the issue (add a comment, transition it) to trigger a fresh anchor render. Or re-enable the toggle.

A Jira comment didn't appear in Slack

• If the comment was made by the Threadmaker app itself (a Slack→Jira sync round-trip), it's intentionally not echoed back to Slack. Origin tracking prevents echo loops.
• If a real Jira user wrote it, check /jira-audit for an error row. Common causes: Slack channel was archived, bot was kicked, or a Slack rate-limit briefly hit.

An attachment didn't sync

Most likely it's over the 2 MB cap. Slack senders see an ephemeral warning when one or more files are dropped. Jira-side attachments over 2 MB simply don't appear in Slack — the comment text still syncs. Upload to your team's storage and paste a link.

"Sync paused" banner

The Atlassian Marketplace license has lapsed past the 7-day grace period. Reactivate the subscription in Atlassian admin to resume sync. The audit log preserves all events that fired during the grace + paused period.

Connection token leaked

Rotate it from the App Home tab → Rotate connection token. The old token becomes invalid immediately. Paste the new token in Apps → Threadmaker (Global) in Jira admin to re-establish the connection. Until you re-paste, Jira-side activity won't deliver to Slack.

Where to get help

• Product questions, sync issues, configuration help: support@cinderlab.io — see Support for hours and what to include in your email.
• Privacy / DPA / data-deletion / DSR: contact@cinderlab.io or see Privacy Policy.
• Status: /healthz returns the current backend health snapshot.
• Security disclosures: security@cinderlab.io with subject "Security disclosure". We acknowledge within one business day under standard responsible-disclosure norms.