Issue tracking integrations

Emdash integrates with Linear, Jira, and GitHub Issues, allowing you to attach issue tracker tickets to tasks and pass them directly to coding agents. Agents receive the full issue context (title, description, labels, etc.) to implement features or fix bugs.

Integrations are optional. You can use Emdash without connecting any issue tracker.

Overview

The issue tracking workflow:

Connect your issue tracker in Settings
Browse issues directly in Emdash
Attach an issue to a task
Agent receives the full issue context
Link PR to the issue when creating a pull request

Supported platforms

Platform	Status	Authentication	Service
Linear	✅ Supported	API key	`LinearService.ts`
Jira	✅ Supported	Site URL + API token	`JiraService.ts`
GitHub Issues	✅ Supported	`gh` CLI	`GitHubService.ts`

Linear integration

Connecting Linear

Generate an API key

Go to Linear Settings → API
Click Create a personal API key
Name it “Emdash” and copy the key

Add to Emdash

Open Settings → Integrations → Linear
Paste your API key
Click Connect

Emdash validates the key by fetching your viewer info and workspace name.

Verify connection

The connection status will show:

✅ Connected with your workspace name
⚠️ Error if authentication failed

Using Linear issues

Browse issues
Search issues
Attach to task

In any task, click Attach Issue and select Linear to browse:

Open issues from your workspace
Issues filtered by state.type not in ["completed", "cancelled"]
Up to 50 most recently updated issues

Use the search box to find issues by:

Issue ID (e.g., ENG-123)
Title keywords
Description text

Emdash uses Linear’s searchIssues GraphQL query for full-text search.

Click an issue to attach it. The agent receives:

# Issue: ENG-123 - Implement dark mode

**Status**: In Progress
**Assignee**: Alice Smith
**Team**: Engineering
**Project**: Q1 2024

## Description
We need to add a dark mode toggle to the app...

[View in Linear](https://linear.app/emdash/issue/ENG-123)

Implementation details

From LinearService.ts:91-129:

async initialFetch(limit = 50): Promise<any[]> {
  const token = await this.getStoredToken();
  if (!token) {
    throw new Error('Linear token not set. Connect Linear in settings first.');
  }

  const query = `
    query ListIssues($limit: Int!) {
      issues(
        first: $limit,
        orderBy: updatedAt,
        filter: { state: { type: { nin: ["completed", "cancelled"] } } }
      ) {
        nodes {
          id
          identifier
          title
          description
          url
          state { name type color }
          team { name key }
          project { name }
          assignee { displayName name }
          updatedAt
        }
      }
    }
  `;

  const response = await this.graphql<{ issues: { nodes: any[] } }>(token, query, {
    limit: sanitizedLimit,
  });

  return response?.issues?.nodes ?? [];
}

Linear tokens are stored securely in your OS keychain via Keytar (service name: emdash-linear).

Jira integration

Connecting Jira

Generate an API token

Go to Atlassian API Tokens
Click Create API token
Name it “Emdash” and copy the token

Find your site URL

Your Jira site URL is the domain you use to access Jira:

Example: https://your-company.atlassian.net

Add to Emdash

Open Settings → Integrations → Jira
Enter:
- Site URL: https://your-company.atlassian.net
- Email: Your Atlassian account email
- API Token: The token from step 1
Click Connect

Emdash validates by calling /rest/api/3/myself.

Using Jira issues

Browse issues
Search issues
Attach to task

Emdash fetches issues using fallback JQL queries to handle limited permissions:

assignee = currentUser() ORDER BY updated DESC
reporter = currentUser() ORDER BY updated DESC
ORDER BY updated DESC (all issues you can see)

If all queries fail, falls back to issue picker for recently viewed issues.

Search by:

Issue key (e.g., PROJ-123) — direct lookup
Text query — JQL text ~ search
Issue number (e.g., 123) — tries all project keys

From JiraService.ts:254-281:

async smartSearchIssues(searchTerm: string, limit = 20): Promise<any[]> {
  const term = (searchTerm || '').trim();
  if (!term) return [];

  const looksLikeKey = /^[A-Za-z][A-Za-z0-9_]*-\d+$/.test(term);
  if (looksLikeKey) {
    // Direct fetch by key
    try {
      const issue = await this.getIssueByKey(siteUrl, email, token, term.toUpperCase());
      if (issue) return this.normalizeIssues(siteUrl, [issue]);
    } catch {
      // Fall back to JQL search
    }
  }

  // Build JQL safely (escape quotes)
  const sanitized = term.replace(/"/g, '\\"');
  const jql = `text ~ "${sanitized}"`;
  const data = await this.searchRaw(siteUrl, email, token, jql, limit);
  return this.normalizeIssues(siteUrl, data);
}

The agent receives normalized issue data:

# Issue: PROJ-123 - Fix login bug

**Status**: In Progress
**Assignee**: Bob Johnson
**Project**: Platform

## Description
Users are unable to log in after password reset...

[View in Jira](https://your-company.atlassian.net/browse/PROJ-123)

ADF description handling

Jira uses Atlassian Document Format (ADF) for rich text. Emdash flattens it to plain text:

// From JiraService.ts:335-351
private static flattenAdf(node: any): string {
  if (!node) return '';
  if (typeof node === 'string') return node;
  if (node.type === 'text') return node.text || '';
  if (Array.isArray(node.content)) {
    const parts = node.content.map((c: any) => JiraService.flattenAdf(c));
    if (['doc', 'bulletList', 'orderedList'].includes(node.type)) {
      return parts.join('\n');
    }
    if (['paragraph', 'heading', 'listItem'].includes(node.type)) {
      return parts.join('');
    }
    return parts.join('');
  }
  return '';
}

Jira credentials are stored in:

API token: OS keychain (Keytar, service name: emdash-jira)
Site URL + email: <userData>/jira.json

GitHub Issues integration

Connecting GitHub Issues

GitHub Issues authentication piggybacks on GitHub CLI:

Install GitHub CLI

# macOS
brew install gh

# Windows
winget install GitHub.cli

# Linux
sudo apt install gh  # Debian/Ubuntu
sudo yum install gh  # RHEL/CentOS

Authenticate with GitHub

gh auth login

Follow the prompts to authenticate via browser or token.

Verify in Emdash

Open Settings → GitHub. If authenticated, you’ll see:

✅ Connected with your GitHub username
Your avatar and profile

GitHub Issues integration requires gh CLI. It does not work with GitHub OAuth tokens stored in Emdash alone.

Using GitHub Issues

Browse issues
Search issues
Attach to task

Issues are project-specific. When you attach an issue to a task:

Emdash runs gh issue list in the project directory
Fetches open issues (state: open)
Shows up to 50 most recently updated issues

From GitHubService.ts:491-521:

async listIssues(projectPath: string, limit: number = 50): Promise<any[]> {
  const fields = ['number', 'title', 'url', 'state', 'updatedAt', 'assignees', 'labels'];
  const { stdout } = await this.execGH(
    `gh issue list --state open --limit ${safeLimit} --json ${fields.join(',')}`,
    { cwd: projectPath }
  );
  const list = JSON.parse(stdout || '[]');
  if (!Array.isArray(list)) return [];
  return list;
}

Search within the current project:

async searchIssues(
  projectPath: string,
  searchTerm: string,
  limit: number = 20
): Promise<any[]> {
  const { stdout } = await this.execGH(
    `gh issue list --state open --search ${JSON.stringify(term)} --limit ${safeLimit} --json ${fields.join(',')}`,
    { cwd: projectPath }
  );
  return JSON.parse(stdout || '[]');
}

The agent receives:

# Issue #42: Add dark mode toggle

**Status**: open
**Assignees**: @alice, @bob
**Labels**: enhancement, ui

## Description
We should add a dark mode toggle in the settings panel...

[View on GitHub](https://github.com/org/repo/issues/42)

GitHub Issues requires the project to be a GitHub repository. For non-GitHub projects, use Linear or Jira instead.

Credential storage summary

Platform	Storage	Service Name	Location
Linear	Keytar	`emdash-linear`	`api-token` account
Jira (token)	Keytar	`emdash-jira`	`api-token` account
Jira (config)	JSON file	—	`<userData>/jira.json`
GitHub	Keytar + `gh` CLI	`emdash-github`	`github-token` account

Keychain locations:

macOS: Keychain Access.app
Linux: libsecret (GNOME Keyring, KWallet)
Windows: Windows Credential Manager

Disconnecting integrations

To disconnect an integration:

Go to Settings → Integrations
Select the platform (Linear/Jira/GitHub)
Click Disconnect

Emdash will:

Remove credentials from the OS keychain
Clear any cached data
Stop fetching issues from that platform

Disconnecting an integration does not remove issues already attached to tasks. The issue metadata remains in the Emdash database.

Troubleshooting

Linear: Invalid API key

Symptom: “Unable to retrieve Linear account information”Solutions:

Verify the API key is correct (regenerate if needed)
Check the key has the required scopes (read:issues, write:issues)
Ensure your Linear workspace is active

Jira: 401 Unauthorized

Symptom: “Jira API error 401”Solutions:

Verify your Atlassian email is correct
Regenerate your API token
Ensure your Jira site URL is correct (https:// required)
Check you have access to the Jira project

GitHub: gh not found

Symptom: “GitHub CLI not installed”Solutions:

Install gh CLI: brew install gh (macOS)
Authenticate: gh auth login
Restart Emdash to detect the CLI
Check PATH includes gh location

No issues appear

Symptom: Issue list is empty despite having open issuesSolutions:

Linear: Check filter excludes completed/cancelled issues
Jira: Verify you have permission to view issues (try JQL in Jira web)
GitHub: Ensure the project is a GitHub repo with issues enabled

Best practices

Use dedicated API keys

Create separate API keys for Emdash (not your personal keys) for easier revocation.

Link PRs to issues

When creating PRs, Emdash can automatically reference the linked issue in the description.

Keep issue context minimal

Large issue descriptions can overwhelm agents. Summarize key requirements in the task description.

Rotate credentials regularly

Regenerate API keys periodically for security.

Get Started

Core Concepts

Features

Configuration

Guides

Issue tracking integrations

Overview

Supported platforms

Linear integration

Connecting Linear

Using Linear issues

Implementation details

Jira integration

Connecting Jira

Using Jira issues

ADF description handling

GitHub Issues integration

Connecting GitHub Issues

Using GitHub Issues

Credential storage summary

Disconnecting integrations

Troubleshooting

Best practices

Use dedicated API keys

Link PRs to issues

Keep issue context minimal

Rotate credentials regularly

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Configuration

Guides

​Overview

​Supported platforms

​Linear integration

​Connecting Linear

​Using Linear issues

​Implementation details

​Jira integration

​Connecting Jira

​Using Jira issues

​ADF description handling

​GitHub Issues integration

​Connecting GitHub Issues

​Using GitHub Issues

​Credential storage summary

​Disconnecting integrations

​Troubleshooting

​Best practices

Use dedicated API keys

Link PRs to issues

Keep issue context minimal

Rotate credentials regularly

​Related resources

Build docs developers (and LLMs) love

Overview

Supported platforms

Linear integration

Connecting Linear

Using Linear issues

Implementation details

Jira integration

Connecting Jira

Using Jira issues

ADF description handling

GitHub Issues integration

Connecting GitHub Issues

Using GitHub Issues

Credential storage summary

Disconnecting integrations

Troubleshooting

Best practices

Related resources