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:

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:

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

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

projects:
  overdeck:
    name: "Overdeck CLI"
    path: /home/user/projects/overdeck
    github_repo: eltmon/overdeck

Creating Issues

# 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

Generate an API key at https://linear.app/settings/api
Add to ~/.overdeck.env:
LINEAR_API_KEY=lin_api_xxxxx

Team Mapping

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

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

# 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

Generate a Rally API key from your Rally workspace settings
Add to ~/.overdeck.env:
RALLY_API_KEY=_xxxxx

Configuration

Configure Rally workspace mapping:

# ~/.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:

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.

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:

Workspace and Project Configuration

# In ~/.overdeck.env
RALLY_WORKSPACE=/workspace/12345
RALLY_PROJECT=/project/67890

API Key Permissions
- Ensure API key has read access to the workspace
- Verify key is not expired
Debug Logging
DEBUG=rally pan up
This will log the actual WSAPI queries being sent to Rally, which helps diagnose parse errors.

Test Configuration Use the Settings page “Test Connection” button to validate Rally setup, or call the API directly:

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/:

Log into Rally web UI
Navigate to desired workspace/project
Check URL: https://rally1.rallydev.com/#/workspace/12345/project/67890
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:

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:

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

Project Registry - Managing multiple projects
Quickstart - Initial setup
Core Commands - CLI reference

​Issue Tracker Integration

​Supported Trackers

​Configuration

​Unified Issue ID Parser

​Supported Formats

​Configuration Fields

​Custom ID Patterns

​GitHub Issues

​Setup

​Issue Prefix

​Creating Issues

​Linear Integration

​Setup

​Team Mapping

​Issue States

​GitLab Issues

​Setup

​Issue Prefix

​Rally Integration

​Setup

​Configuration

​Rally ID Formats

​Shadow Mode

​Rally Troubleshooting

​WSAPI Query Parse Errors

​Finding Workspace and Project IDs

​Unified Dashboard

​Multi-Tracker Workflows

​Mixed Tracker Pattern

​Syncing Between Trackers

​Related Guides

Issue Tracker Integration

Supported Trackers

Configuration

Unified Issue ID Parser

Supported Formats

Configuration Fields

Custom ID Patterns

GitHub Issues

Setup

Issue Prefix

Creating Issues

Linear Integration

Setup

Team Mapping

Issue States

GitLab Issues

Setup

Issue Prefix

Rally Integration

Setup

Configuration

Rally ID Formats

Shadow Mode

Rally Troubleshooting

WSAPI Query Parse Errors

Finding Workspace and Project IDs

Unified Dashboard

Multi-Tracker Workflows

Mixed Tracker Pattern

Syncing Between Trackers

Related Guides