Connect trackers

One backlog over GitHub, Linear, Jira, GitLab, Notion, and Slack — synced both ways, statuses kept native.

Peractor's backlog holds tasks from several trackers — and manual tasks — at once. Issues import with their real fields, sync status both ways, route to workflows by rule, and can start runs the moment they land.

How connecting works

In Settings → Issue trackers, pick Add a tracker. Two levels are involved, on purpose:

  • The authorization is organization-level — one OAuth grant or app install per workspace, made once by an admin.
  • Imports are project-level — each project chooses its own repositories, boards, projects, databases, or channels, and keeps its own tasks. Two projects importing the same board don't share anything but the credential.

After an import, the tracker gets its own panel in the Tasks view, mirroring its real board. The setup wizard offers the same tiles on day one.

Statuses stay native

There is no mapping table. A task's status is origin-qualified — your columns are peractor:in-spec, a Linear task moves through your Linear states, a Notion page through your select options. Workflow automation references them the same way (<connector>:<Column>), so one workflow can drive tasks from several trackers, each in its own vocabulary.

Sync, in both directions

  • Inbound: a poll sweeps every imported unit about every 30 seconds (instant webhooks where the platform offers them — GitHub Issues, Linear, Slack). Title, description, status, priority, assignee, and labels keep following the tracker even while a run owns the task.
  • Outbound: Peractor writes status only through workflow automation (onStatus/setStatus), as the app identity ("Peractor") — a label swap on GitLab, a transition on Jira, a column move on GitHub Projects, a reaction on Slack.
  • Imported tasks are read-only in Peractor — move the issue on its own board and Peractor follows. One writer per direction means no conflicts to resolve.
  • Pruning is careful: issues that vanish from the source drop off the backlog, but run-owned tasks are kept, and any API hiccup aborts the sweep before anything is removed.

Routing: which workflow runs an import

Each tracker's settings page has a Workflow routing panel — rules run top-down, first full match wins, anything unmatched uses the default:

workflows:
  rules:
    - { tags: [release], use: release }
    - { assignee: alice, use: fast-track }
    - { tags: [backend], assignee: bob, use: backend }  # fields AND'd
    - { tag: "workflow-*", use: "$1" }                  # glob + capture
  default: default

Match on labels and/or assignee (Slack: channel and author), case insensitive. The workflow binds at import and re-resolves on updates only until the task has a run.

Auto-run

Each tracker has one switch — Auto-run imported tasks, off by default. On, a task starts its workflow the moment it's imported (at its status-entry phase when one matches). Guardrails: a task with an active run is never re-triggered, issues arriving already-done import without running, and plan limits still apply — excess runs queue.

Attachments reach the agent

Files on an imported issue are recorded at import and downloaded when a run starts — fresh URLs, current file list — then staged into the workspace at .peractor/attachment/ (git-excluded) with their paths listed in the agent's prompt. Limits: 10 MB per file, 25 MB and 10 files per run. Best-effort by design: a missing file becomes a run-log note, never a failed run.

Removing things

Three levels, smallest first: Remove on an imported unit (drops its tasks, except any with a run in flight); the trash on the tracker's rail row (removes the org authorization too); and full revocation, which always lives with the provider (uninstall the GitHub App, remove the Slack app, revoke the OAuth grant).

Per-tracker details: GitHub · Linear · Jira · GitLab · Notion · Slack