Skip to main content

​
Issue Tracker Integration

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

​
Supported Trackers

TrackerConfiguration
GitHub IssuesGITHUB_TOKEN or gh auth login
LinearLINEAR_API_KEY in .panopticon.env
GitLab IssuesGITLAB_TOKEN or glab auth login
JiraJIRA_API_KEY in .panopticon.env
RallyRALLY_API_KEY in .panopticon.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 ~/.panopticon.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
JIRA_API_KEY=xxxxx         # For Jira-tracked projects
RALLY_API_KEY=_xxxxx       # For Rally-tracked projects

​
Linear Integration

Linear is Panopticon’s primary issue tracker. Most features are designed around Linear’s workflow.

​
Setup

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

​
Team Mapping

Map Linear teams to local projects in ~/.panopticon/projects.yaml: 
projects:
  myapp:
    name: "My Application"
    path: /home/user/projects/myapp
    linear_team: APP  # Linear team prefix

​
Issue States

Panopticon tracks and updates Linear issue states:
StateDescription
BacklogNot started
PlanningPlanning session active
In ProgressAgent working on issue
In ReviewAwaiting code review
DoneWork completed

​
GitHub Issues

GitHub Issues work as a secondary tracker, syncing to the dashboard alongside Linear.

​
Setup

# Authenticate with GitHub CLI
gh auth login

# Or set a token in .panopticon.env
GITHUB_TOKEN=ghp_xxxxx

​
Issue Prefix

GitHub Issues are prefixed with the repository name: 
myn-123      # Linear issue (MIN team)
panopticon#45  # GitHub issue (panopticon repo)

​
Creating Issues

# Via CLI
gh issue create --title "New feature" --body "Description"

# Or via dashboard - select GitHub project

​
GitLab Issues

GitLab Issues integrate similarly to GitHub Issues.

​
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

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

​
Configuration

Configure Rally workspace mapping: 
# ~/.panopticon/projects.yaml
projects:
  enterprise-app:
    name: "Enterprise Application"
    path: /home/user/projects/enterprise
    rally_workspace: YOUR_WORKSPACE_OID
    rally_project: YOUR_PROJECT_OID

​
Rally Troubleshooting

​
WSAPI Query Parse Errors

If you see errors like Could not parse: Error parsing expression, check:
  1. Workspace and Project Configuration 
    # In ~/.panopticon.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 
    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: 
    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

​
Primary + Secondary Pattern

A common pattern is using Linear as primary with GitHub for open-source components: 
projects:
  myapp:
    name: "My Application"
    linear_team: APP
    # ... standard config

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

​
Syncing Between Trackers

Panopticon 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
- panopticon#45 (GitHub) - Dependency fix needed