> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Issue Tracker Integration

> Connect GitHub, Linear, GitLab, and Rally

# Issue Tracker Integration

Overdeck integrates with popular issue tracking systems to provide unified project management.

## Supported Trackers

| Tracker | Configuration |
| - | - |
| **GitHub Issues** | `GITHUB_TOKEN` or `gh auth login` |
| **Linear** | `LINEAR_API_KEY` in `.overdeck.env` |
| **GitLab Issues** | `GITLAB_TOKEN` or `glab auth login` |
| **Rally** | `RALLY_API_KEY` in `.overdeck.env` |

All trackers are equal — configure whichever your projects use. The dashboard displays issues from all configured trackers in a unified Kanban board.

## Configuration

Create `~/.overdeck.env`:

```bash theme={null}
GITHUB_TOKEN=ghp_xxxxx     # For GitHub-tracked projects
LINEAR_API_KEY=lin_api_xxxxx  # For Linear-tracked projects
GITLAB_TOKEN=glpat-xxxxx  # For GitLab-tracked projects
RALLY_API_KEY=_xxxxx       # For Rally-tracked projects
```

## Unified Issue ID Parser

Overdeck uses a unified issue ID parser that handles multiple formats through configurable project patterns. This eliminates the hardcoded `PREFIX-NUMBER` assumption that doesn't work for Rally-style IDs.

### Supported Formats

| Format | Example | Parser Behavior |
| - | - | - |
| **Standard** | `MIN-123`, `PAN-456` | Prefix and number separated by dash |
| **Rally** | `F29698`, `US12345` | Type prefix directly concatenated with number |
| **Custom** | `PROJ12345` | Per-project regex pattern via `issue_pattern` |

### Configuration Fields

| Field | Description |
| - | - |
| `tracker` | Tracker type: `linear`, `github`, `gitlab`, `rally` |
| `issue_prefix` | Single prefix (e.g., `"MIN"`) |
| `issue_prefixes` | Array of prefixes mapping to one project (e.g., `[F, US, DE, TA]`) |
| `issue_pattern` | Custom regex with two capture groups: `^(PREFIX)-(\d+)$` |

### Custom ID Patterns

For non-standard trackers, define a custom regex pattern:

```yaml theme={null}
projects:
  myproject:
    tracker: custom
    issue_pattern: "^(PROJ)-(\\d+)$"  # Matches PROJ-123
```

## GitHub Issues

GitHub Issues provides full integration with PRs, status updates, and automated merging.

### Setup

```bash theme={null}
# Authenticate with GitHub CLI (recommended)
gh auth login

# Or set a token in .overdeck.env
GITHUB_TOKEN=ghp_xxxxx
```

### Issue Prefix

GitHub Issues use an uppercase project key as prefix, derived from the project name in `projects.yaml`:

```
PAN-45       # GitHub issue #45 on the overdeck project
KRUX-3       # GitHub issue #3 on the krux project
```

The prefix is the project key uppercased. Configure via `projects.yaml`:

```yaml theme={null}
projects:
  overdeck:
    name: "Overdeck CLI"
    path: /home/user/projects/overdeck
    github_repo: eltmon/overdeck
```

### Creating Issues

```bash theme={null}
# Via CLI
gh issue create --title "New feature" --body "Description"

# Or via dashboard - select GitHub project
```

## Linear Integration

Linear provides full integration with cycles, labels, and status updates.

### Setup

1. Generate an API key at [https://linear.app/settings/api](https://linear.app/settings/api)
2. Add to `~/.overdeck.env`:
   ```bash theme={null}
   LINEAR_API_KEY=lin_api_xxxxx
   ```

### Team Mapping

Map Linear teams to local projects in `~/.overdeck/projects.yaml`:

```yaml theme={null}
projects:
  myapp:
    name: "My Application"
    path: /home/user/projects/myapp
    issue_prefix: APP  # Linear team prefix
```

### Issue States

Overdeck tracks and updates Linear issue states:

| State | Description |
| - | - |
| **Backlog** | Not started |
| **Planning** | Planning session active |
| **In Progress** | Agent working on issue |
| **In Review** | Awaiting code review |
| **Done** | Work completed |

## GitLab Issues

GitLab Issues integrate similarly to GitHub Issues, with MR management support.

### Setup

```bash theme={null}
# Authenticate with GitLab CLI
glab auth login
```

### Issue Prefix

```
myproject!23  # GitLab issue/MR
```

## Rally Integration

Rally (CA Agile Central) is supported for enterprises using Rally for project management.

### Setup

1. Generate a Rally API key from your Rally workspace settings
2. Add to `~/.overdeck.env`:
   ```bash theme={null}
   RALLY_API_KEY=_xxxxx
   ```

### Configuration

Configure Rally workspace mapping:

```yaml theme={null}
# ~/.overdeck/projects.yaml
projects:
  enterprise-app:
    name: "Enterprise Application"
    path: /home/user/projects/enterprise
    tracker: rally
    issue_prefixes: [F, US, DE, TA, TC]  # All Rally artifact types → this project
    rally_workspace: YOUR_WORKSPACE_OID
    rally_project: YOUR_PROJECT_OID
```

### Rally ID Formats

Rally uses a different ID format than most trackers. Instead of `PREFIX-NUMBER`, Rally uses **type prefixes concatenated with numbers**:

| Prefix | Artifact Type | Example |
| - | - | - |
| `F` | Feature | `F29698` |
| `US` | User Story | `US12345` |
| `DE` | Defect | `DE118304` |
| `TA` | Task | `TA4567` |
| `TC` | Test Case | `TC78901` |

Overdeck's unified issue ID parser handles these formats automatically. Configure `issue_prefixes` to map all Rally artifact types to your project:

```yaml theme={null}
issue_prefixes: [F, US, DE, TA, TC]
```

With this configuration:

* `pan workspace create F29698` → resolves to your project
* `pan workspace create US12345` → resolves to your project
* `pan workspace create DE118304` → resolves to your project

### Shadow Mode

Rally integration supports **shadow mode** — tracking Rally issues locally without modifying the tracker. This is useful for teams transitioning to Overdeck or evaluating the workflow.

```yaml theme={null}
projects:
  enterprise-app:
    shadow:
      enabled: true
      trackers:
        rally: true
```

In shadow mode:

* Issue states are tracked locally in Overdeck
* No updates are sent to Rally
* Agents can read Rally data but changes stay local

### Rally Troubleshooting

#### WSAPI Query Parse Errors

If you see errors like `Could not parse: Error parsing expression`, check:

1. **Workspace and Project Configuration**
   ```bash theme={null}
   # In ~/.overdeck.env
   RALLY_WORKSPACE=/workspace/12345
   RALLY_PROJECT=/project/67890
   ```

2. **API Key Permissions**
   * Ensure API key has read access to the workspace
   * Verify key is not expired

3. **Debug Logging**
   ```bash theme={null}
   DEBUG=rally pan up
   ```
   This will log the actual WSAPI queries being sent to Rally, which helps diagnose parse errors.

4. **Test Configuration**
   Use the Settings page "Test Connection" button to validate Rally setup, or call the API directly:
   ```bash theme={null}
   curl -X POST http://localhost:3011/api/rally/validate \
     -H 'Content-Type: application/json' \
     -d '{"apiKey": "YOUR_KEY", "workspace": "/workspace/12345", "project": "/project/67890"}'
   ```

#### Finding Workspace and Project IDs

Rally workspace and project IDs are numeric strings prefixed with `/workspace/` or `/project/`:

1. Log into Rally web UI
2. Navigate to desired workspace/project
3. Check URL: `https://rally1.rallydev.com/#/workspace/12345/project/67890`
4. Use: `RALLY_WORKSPACE=/workspace/12345` and `RALLY_PROJECT=/project/67890`

## Unified Dashboard

The dashboard shows issues from all configured trackers:

* **Kanban board** displays issues by status
* **Filter by tracker** to focus on specific systems
* **Create workspaces** from any tracker
* **Spawn agents** regardless of tracker source

## Multi-Tracker Workflows

### Tracker and Code Host Can Differ

The issue tracker and code host are independent project settings. The `tracker` field selects where issues and workflow states live, while `github_repo` or `gitlab_repo` selects where Overdeck reads pull requests or merge requests.

Set `tracker` explicitly when one project uses different systems. This example tracks `APP-*` issues in Linear while hosting source code and pull requests on GitHub:

```yaml theme={null}
projects:
  myapp:
    name: "My Application"
    path: /home/user/projects/myapp
    issue_prefix: APP
    tracker: linear
    linear_project: My Application
    github_repo: myorg/myapp
```

This setup requires both Linear credentials and authenticated GitHub access. Overdeck queries Linear for issue state and labels, then queries GitHub for pull-request evidence. Keep `github_repo`; removing it would hide GitHub pull requests from pipeline membership.

If a Linear-tracked, GitHub-hosted project reports a GitHub Issues request such as `/repos/myorg/myapp/issues?...labels=planning` instead, check for a missing `tracker: linear`. Without that explicit setting, tracker inference may select GitHub Issues from `github_repo`. A GitHub 404 can be misleading here because private repositories also return 404 when the selected GitHub credential lacks access.

Pipeline membership is refreshed in the background and cached per project. If a GitHub GraphQL call fails without returning a response (a network error, a `gh` crash, or a 30-second timeout), Overdeck retries it once after one second. If the refresh still fails, the last successful membership snapshot keeps serving the dashboard and the server log records `[pipeline-membership] refresh failed for <project>; keeping last-good snapshot:` followed by `gh`'s own error output (exit code or timeout, attempt number, and stderr), so the cause is visible without re-running the query by hand. A GraphQL response that carries only `errors` is not retried.

### Different Trackers Across Projects

A separate pattern is using different trackers for different projects:

```yaml theme={null}
projects:
  myapp:
    name: "My Application"
    issue_prefix: APP
    tracker: linear

  myapp-oss:
    name: "My App OSS Components"
    issue_prefix: OSS
    tracker: github
    github_repo: myorg/myapp-oss
```

### Syncing Between Trackers

Overdeck doesn't sync issues between trackers — each issue lives in its source system. However, agents can reference issues from multiple trackers:

```markdown theme={null}
<!-- In an agent's STATE.md -->
Related issues:
- MIN-123 (Linear) - Parent feature
- PAN-45 (GitHub) - Dependency fix needed
```

## Related Guides

* [Project Registry](/configuration/projects) - Managing multiple projects
* [Quickstart](/quickstart) - Initial setup
* [Core Commands](/cli/core-commands) - CLI reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.