Tracking providers

The tracking section of .flowforge/config.yml tells FlowForge which issue tracker to validate ticket references against, where to push session and time data, and whether to operate online at all. This page walks each supported provider. For the field shape, see the config.yml schema.

Section shape

tracking:
  provider: github | linear | jira | notion | local   # default: github
  repository: string                                  # optional
  syncEnabled: true | false                           # default: true

All three fields are optional. If the section is omitted entirely, FlowForge runs with the defaults: provider: github, no explicit repository, and sync enabled.

Choosing a provider

Provider	What it talks to	Network access required
github	GitHub Issues on a single repository.	Yes
linear	Linear workspace tickets (Linear-style keys).	Yes
jira	Jira Cloud or Server projects (Jira-style keys).	Yes
notion	Notion databases used as a tracker.	Yes
local	On-disk only. No external tracker.	No

If you are unsure which provider to pick, start with github — it has the largest installed base and is the path FlowForge exercises most thoroughly. Switching providers is just an edit to config.yml; FlowForge does not migrate ticket data between providers automatically.

github

tracking:
  provider: github
  repository: my-org/my-repo
  syncEnabled: true

repository for GitHub uses the conventional owner/repo slug. If repository is omitted, FlowForge attempts to infer it from the local git remote (typically origin). Explicitly setting it is recommended for repositories with multiple remotes or for projects whose tracker repository is different from the source repository.

GitHub-style ticket references (#123) are recognized by the ticket-reference rule out of the box. No additional configuration is needed for the rule to accept them.

linear

tracking:
  provider: linear
  repository: ENG       # Linear team key
  syncEnabled: true

For Linear, repository is conventionally used to disambiguate the team or workspace. Linear ticket keys follow the TEAM-123 shape (for example ENG-456), which the ticket-reference rule accepts via its uppercase-prefix pattern.

Use Linear when your team already lives in Linear and you want FlowForge sessions to surface alongside Linear’s native time and status tracking.

jira

tracking:
  provider: jira
  repository: PROJ      # Jira project key
  syncEnabled: true

For Jira, repository typically holds the Jira project key (the prefix of issue keys, for example PROJ from PROJ-123). Jira-style keys are accepted by the ticket-reference rule.

Both Jira Cloud and Jira Server are supported through this provider. Authentication is handled by environment configuration outside config.yml; the configuration file declares the project, not the credentials.

notion

tracking:
  provider: notion
  repository: <database-id>
  syncEnabled: true

Notion is a less common but supported tracker. repository here holds the identifier of the Notion database that backs your ticket workflow. Tickets are referenced using whichever scheme that database uses for its primary key column; if you are using bracket-wrapped keys (for example [ENG-123]), the ticket-reference rule accepts them directly.

local

tracking:
  provider: local
  syncEnabled: false

The local provider runs FlowForge fully offline. Sessions, time entries, and ticket validation all happen against on-disk state only — no remote calls are made and no credentials are required. This is the right choice for:

• A throwaway sandbox where you do not want noise on a real tracker.
• An environment without network access (an air-gapped lab, a flight, a disaster-recovery drill).
• Spike branches where you want FlowForge’s rule enforcement and time tracking but not the social cost of a half-baked ticket.

With provider: local, syncEnabled has no effect — there is no remote to sync with. Set it to false explicitly so the intent is obvious to future readers.

repository

tracking:
  repository: my-org/my-repo

The repository field is a free-form string the provider interprets in its own conventions:

• For github, it is the owner/repo slug.
• For linear, it is conventionally the team key.
• For jira, it is conventionally the project key.
• For notion, it is a database identifier.
• For local, it is unused.

repository is optional. When it is absent, the provider falls back to inferring the value from environment context (most commonly the local git remote) where that is meaningful.

syncEnabled

tracking:
  syncEnabled: true   # default

Controls whether FlowForge pushes data to the configured provider:

• true (default) — sessions, status updates, and time totals are synchronized to the tracker as they happen. This is the normal operating mode.
• false — FlowForge runs every rule, validates every ticket reference, and tracks time on disk, but does not call the provider. The provider configuration still has to be valid (FlowForge needs to know which ticket-reference shapes to accept), but no network round-trips happen.

Practical reasons to set syncEnabled: false temporarily:

• The upstream tracker is undergoing maintenance and you want FlowForge to stop fan-out errors in your terminal.
• You are on a flight or behind a captive portal and want session times to record locally without retry storms.
• You are running an experimental branch where ticket comments would be noise.

When you set syncEnabled: false, no data is lost — FlowForge keeps the local record. Re-enabling sync resumes normal behavior; FlowForge does not back-fill the gap. If you need a clean state on the tracker side, do that manually.

See also

• config.yml schema — top-level field reference.
• Built-in rules > ticket-reference — how ticket references are validated against your tracker.
• Project type examples — full configs that include the tracking section.