Skip to main content
The tracker configuration section defines how Symphony connects to your issue tracking system to poll for work and fetch issue details.

​
Configuration

WORKFLOW.md
tracker:
  kind: linear
  project_slug: "symphony-0c79b11b75ea"
  active_states:
    - Todo
    - In Progress
    - Merging
    - Rework
  terminal_states:
    - Closed
    - Cancelled
    - Canceled
    - Duplicate
    - Done
  api_key: $LINEAR_API_KEY

​
Fields

​
kind
string
required
Issue tracker type. Currently only linear is supported.Required for dispatch. The orchestrator validates this field before starting the polling loop.
​
project_slug
string
required
Linear project identifier (the project’s slugId value).Required when kind: linear. Used to filter issues during candidate polling.Example: "symphony-0c79b11b75ea"
​
active_states
array
default:"[\"Todo\", \"In Progress\"]"
List of issue states that trigger agent dispatch.Issues in these states are eligible for orchestration. The orchestrator polls for issues matching these states on each tick.Can be specified as:
  • YAML array: ["Todo", "In Progress"]
  • Comma-separated string: "Todo, In Progress"
State matching is case-insensitive after trimming.
​
terminal_states
array
List of issue states considered complete.Issues that transition to these states:
  • Are stopped if currently running
  • Have their workspaces cleaned up on service startup
  • Are excluded from retry scheduling
State matching is case-insensitive after trimming.
​
api_key
string
required
Authentication token for the issue tracker API.Supports environment variable indirection using $VAR_NAME syntax:
  • $LINEAR_API_KEY reads from the LINEAR_API_KEY environment variable
  • Literal token strings are also accepted (not recommended for production)
Required when kind: linear. If the value resolves to an empty string, it’s treated as missing.
The canonical environment variable for Linear is LINEAR_API_KEY.
​
endpoint
string
default:"https://api.linear.app/graphql"
GraphQL API endpoint for the Linear tracker.Automatically defaults to https://api.linear.app/graphql when kind: linear.
​
assignee
string
Filter issues by assignee (optional).Supports environment variable indirection using $VAR_NAME syntax. Canonical environment variable: LINEAR_ASSIGNEE.

​
Validation

The orchestrator performs preflight validation before dispatch:
  1. Startup validation: Checks configuration before starting the polling loop
  2. Per-tick validation: Re-validates before each dispatch cycle
Validation failures:
  • Block new dispatches (reconciliation continues)
  • Emit operator-visible errors in logs
  • Use the last known good configuration for running sessions

​
Configuration Reloading

Tracker configuration changes are applied dynamically:
  • Active/terminal state changes affect future dispatch and reconciliation decisions
  • Running sessions continue with their original configuration
  • No restart required for configuration updates

​
Examples

​
Basic Linear Integration

WORKFLOW.md
tracker:
  kind: linear
  project_slug: "my-project-abc123"
  api_key: $LINEAR_API_KEY

​
Custom State Workflow

WORKFLOW.md
tracker:
  kind: linear
  project_slug: "symphony-0c79b11b75ea"
  active_states:
    - Todo
    - In Progress
    - Merging
    - Rework
  terminal_states:
    - Closed
    - Cancelled
    - Canceled
    - Duplicate
    - Done
  api_key: $LINEAR_API_KEY

​
With Assignee Filter

WORKFLOW.md
tracker:
  kind: linear
  project_slug: "my-project"
  assignee: $LINEAR_ASSIGNEE
  api_key: $LINEAR_API_KEY
  • polling - Control how often Symphony checks for new work
  • agent - Manage concurrency limits for running agents

Build docs developers (and LLMs) love

Get started for freeTalk to us