Connect trackers

Sync issues from GitHub, Linear, Jira, GitLab, Notion, or Slack — as Peractor tasks, kept in step both ways.

A connected tracker's issues are Peractor tasks that came from somewhere. They stand on your project's one board beside the tasks you wrote yourself, you edit them like any other task, and every change is kept in step with the tracker wherever the tracker can hold it. 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 someone with Manage connectors.
  • What you follow is project-level — each project connects its own repositories, boards, projects, databases, or channels, and keeps its own tasks; connecting one takes Manage connectors too. Two projects following the same board share nothing but the credential.

A connection's Projects say which projects may use it: All projects, which is how every connection starts, or Only these. A project that isn't on the list doesn't see the connection, and its lists stop syncing. Each project says what it takes from the connection, so taking one off tells you what stops before you save.

Once a list is connected, its issues appear on the project's board, each with its tracker's mark and key. The setup wizard offers the same tiles on day one.

One board, on your statuses

Every task sits in one of your project's statuses. Each tracker's states map onto them by category — backlog, unstarted, started, completed, canceled — so Linear's In Progress lands in your started column without anyone setting it up. A state with the same name as one of your statuses lands there first.

Change it on the tracker's settings page, under Statuses: pick the status each state lands in, and under Writes back as, the state a move to each of your statuses writes to the tracker. A tracker with few states writes the nearest one — every open column of a GitHub issue writes Open, and a move only reads back when the tracker's state actually changes, so an open issue never pulls its task back out of In Progress.

Workflow automation names your statuses too, so one workflow drives every task, whichever tracker it came from.

Two writers

  • Edit it anywhere. Title, description, status, priority, assignees, labels and due date go back to Linear, Jira, GitHub Issues and GitLab as you change them here (GitHub has no priority or due date; Linear also takes the estimate). GitHub Projects, pull requests, Notion, Slack and Discord take status and comments. A task says which of its fields sync, and which stay in Peractor.
  • The later edit wins. When both sides changed the same field between syncs, the task keeps the later one and shows a line naming both — one press takes the other instead.
  • Nothing is dropped. A write the tracker refuses is shown on the task and retried; after a few tries it waits for you to press Retry.
  • Comments cross both ways. What you write here posts to the issue as Name via Peractor, from the connection's account, and the tracker's comments arrive here under their writer's name.
  • People are matched by email or sign-in. Fix the rest in the tracker's People section; nobody is matched by name alone.
  • Inbound is a poll about every 30 seconds, with instant webhooks where the platform offers them — GitHub, Linear, Slack.

New tasks

A task made here stays here unless it asks to go out. Also create in Linear on the New task form, or Create in Linear on an existing task, makes the issue and links the two. To send every task people file, pick a list under New tasks also go to — in Settings → General on the dashboard and the desktop app, and Settings → Task Tracker on the phones and the Mac. Tasks a run files — a plan step's — still stay here unless they ask, so a plan never fills your tracker with machine-made issues.

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.

Unlinking and removing

Unlink a task to stop syncing it and keep it: it stays here with its runs and comments, and the issue is left as it is. Deleting a synced task never touches the issue either, and the issue is not brought back. An issue deleted or moved out of its list leaves its task here, unlinked.

Four levels, smallest first:

  1. Disconnect a connected list — unlinks every task it synced and keeps them all, which is how you leave a tracker.
  2. Take a project off the connection — untick it under the connection's Projects. Its lists stop syncing there, and other projects keep the connection.
  3. Disconnect Linear (or Jira, GitLab or Notion) at the foot of the tracker's page — takes the organization's authorization away from every project. The tasks it synced into this project stay, unlinked.
  4. 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.