Configuration reference

IssueSuite reads settings from issue_suite.config.yaml. Each section below documents defaults and customization options.

Configuration structure

graph TB
    subgraph "Core Configuration"
        VERSION[version]
        SOURCE[source<br/>spec file settings]
        DEFAULTS[defaults<br/>labels & milestones]
        BEHAVIOR[behavior<br/>dry-run & diffs]
    end

    subgraph "Output & Artifacts"
        OUTPUT[output<br/>JSON files]
        SCHEMAS[schemas<br/>schema files]
    end

    subgraph "Integration"
        GITHUB[github<br/>repo & projects]
        AUTH[github.app<br/>authentication]
    end

    subgraph "Operational"
        LOGGING[logging<br/>format & level]
        PERF[performance<br/>benchmarking]
        CONC[concurrency<br/>parallel ops]
        ENV[environment<br/>runtime overrides]
    end

    subgraph "Extensions"
        PLUGINS[plugins<br/>entry points]
        TELEMETRY[telemetry<br/>event emission]
    end

    VERSION --> SOURCE
    SOURCE --> DEFAULTS
    DEFAULTS --> BEHAVIOR

    BEHAVIOR --> OUTPUT
    OUTPUT --> SCHEMAS

    GITHUB --> AUTH

    style SOURCE fill:#e1f5ff
    style GITHUB fill:#fff3cd
    style OUTPUT fill:#d4edda

version

Keep at 1 unless a migration script indicates otherwise.

source

Key	Type	Default	Description
`file`	string	`ISSUES.md`	Path to the spec file relative to the config.
`id_pattern`	regex	`^[a-z0-9][a-z0-9-_]*$`	Allowed slug format.
`milestone_required`	bool	`false`	Require each spec to provide a milestone.
`milestone_pattern`	regex	—	Enforce milestone naming conventions.
`auto_status_label`	bool	`true`	Automatically apply status labels during sync.

defaults

Key	Type	Default	Description
`inject_labels`	list[str]	`[]`	Labels added to every issue when syncing.
`ensure_labels_enabled`	bool	`false`	Create missing labels automatically.
`ensure_milestones_enabled`	bool	`false`	Create missing milestones automatically.
`ensure_milestones`	list[str]	`Sprint 0: Mobilize & Baseline`, `M1: Real-Time Foundation`, `M2: Performance & Validation`, `M3: Advanced Analytics`	Ensures required milestones exist.

behavior

Key	Type	Default	Description
`dry_run_default`	bool	`false`	Force dry-run mode unless `--update` is provided.
`truncate_body_diff`	int	`80`	Length of diff previews in plan output.
`emit_change_events`	bool	`false`	Emit change events for integrations.

output

Key	Default	Purpose
`summary_json`	`issues_summary.json`	Sync totals and plan summary.
`plan_json`	`issues_plan.json`	Dry-run action plan (`sync --plan-json`).
`export_json`	`issues_export.json`	Output for `issuesuite export`.
`report_html`	`issues_report.html`	Reserved for future HTML reports.
`hash_state_file`	`.issuesuite_hashes.json`	Tracks spec hashes to detect changes.
`mapping_file`	`.issuesuite_mapping.json`	Legacy mapping file (superseded by `.issuesuite/index.json`).
`lock_file`	`.issuesuite_lock`	Prevents concurrent runs.

schemas

Key	Default	Description
`schema_export_file`	`issue_export.schema.json`	Destination for the export schema generated by `issuesuite schema`.
`schema_summary_file`	`issue_change_summary.schema.json`	Destination for the summary schema generated by `issuesuite schema`.
`schema_ai_context_file`	`ai_context.schema.json`	Destination for the AI context schema when available.
`schema_version`	Summary schema version	Override the schema version advertised in generated files.

github

Key	Default	Description
`repo`	`null`	`owner/repo` identifier for the target repository.
`project.enable`	`false`	Opt into GitHub Projects (v2) integration.
`project.number`	`null`	Project number when enabled.
`project.field_mappings`	`{}`	Map IssueSuite metadata to project fields.
`app.enabled`	`false`	Use GitHub App authentication.
`app.*`	—	Provide `app_id`, `private_key_path`, and `installation_id`.

logging

Key	Default	Description
`json_enabled`	`false`	Emit structured JSON logs.
`level`	`INFO`	Minimum log level.

performance

Key	Default	Description
`benchmarking`	`false`	Emit metrics to `performance_report.json`.

concurrency

Key	Default	Description
`enabled`	`false`	Enable parallel GitHub operations.
`max_workers`	`4`	Number of concurrent workers when enabled.

environment

Key	Default	Description
`enabled`	`true`	Enable environment helper integration.
`load_dotenv`	`true`	Load `.env` automatically.
`dotenv_path`	`null`	Custom `.env` path.

telemetry

Key	Default	Description
`enabled`	`false`	Opt into local telemetry (JSONL events).
`store_path`	`$HOME/.issuesuite/telemetry.jsonl`	Destination for captured events.

extensions

Key	Default	Description
`enabled`	`true`	Enable plugin loading.
`disabled`	`[]`	Names of entry-point plugins to skip.

Refer to the Architecture explanation to see how configuration ties into module responsibilities.