Connect trackers

Sync issues in from GitHub, Linear, Jira, GitLab, Notion, or Slack — with their real fields and statuses.

Peractor's backlog holds tasks from several trackers — and tasks you wrote yourself — at once. Issues sync in with their real fields, statuses sync both ways, work routes to a workflow by rule, and a run can start the moment an issue lands.

How connecting works

In Settings → Issue trackers, choose 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.
  • What you follow is project-level — each project connects its own repositories, boards, projects, databases, or channels, and keeps its own tasks. Two projects following the same board share nothing but the credential.

Once a list is connected, that tracker gets its own board in the Tasks view, mirroring its real statuses. The setup wizard offers the same tiles on day one.

Statuses stay native

There is no mapping table. A task's status is qualified by where it came from — your own statuses are peractor:in-spec, a Linear task moves through your Linear states, a Notion page through your select options.

Workflow automation refers to them the same way (<connector>:<Status>), so one workflow can drive tasks from several trackers, each in its own vocabulary.

Sync, in both directions

  • Inbound: a poll sweeps every connected list about every 30 seconds, with instant webhooks where the platform offers them — GitHub, 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, as the app identity — a label swap on GitLab, a transition on Jira, a status move on GitHub Projects, a reaction on Slack.
  • Synced tasks are read-only in their core fields. Move the issue on its own board and Peractor follows. One writer per direction means no conflicts to resolve. Everything Peractor adds on top — comments, estimates, relations, milestones, cycles — is still yours.
  • Pruning is careful: issues that vanish from the source drop off the backlog, but tasks with a run are kept, and any API hiccup aborts the sweep before anything is removed.

Routing: which workflow runs a synced issue

Each tracker's settings page has a Workflow routing panel. Rules run top down, first full match wins, and 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" }                  # wildcard + capture
  default: default

Match on labels and assignee — for Slack, channel and author — case insensitively. The workflow binds when the issue arrives and re-resolves on updates only until the task has a run.

Auto-run

Each tracker has one switch: Run new tasks automatically, off by default. On, a task starts its workflow the moment it arrives — at its status-entry phase when one matches.

Guardrails: a task with an active run is never re-triggered, issues arriving already-done land without running, and plan limits still apply so excess runs queue.

Attachments reach the agent

Files on a synced issue are recorded as they arrive and downloaded when a run starts, then staged into the workspace with their paths listed in the agent's prompt. Limits are 10 MB per file, and 25 MB across at most 10 files per run. A file that cannot be fetched becomes a note in the run log, never a failed run.

Removing things

Three levels, smallest first:

  1. Disconnect a connected list — drops its tasks, except any with a run in flight.
  2. Remove the tracker from its row — takes the organization's authorization with it.
  3. Revoke at the provider — uninstall the GitHub app, remove the Slack app, revoke the OAuth grant. This always lives with the provider.

Per-tracker detail: GitHub · Linear · Jira · GitLab · Notion · Slack. Moving off a tracker entirely? See Import.