> ## 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

### Mixed Tracker Pattern

A common pattern is using different trackers for different projects:

```yaml theme={null}
projects:
  myapp:
    name: "My Application"
    issue_prefix: APP
    # Linear for this project

  myapp-oss:
    name: "My App OSS Components"
    github_repo: myorg/myapp-oss
    # GitHub Issues for this project
```

### 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