Staging
Connect a tracker
On staging, comments do not go to a coding agent on your machine. Passback files each one in the tracker your team already uses: Linear, Plane, GitHub, Azure DevOps, GitLab, Trello, Notion, Asana, Jira or ClickUp. You connect the tracker once per site, in the dashboard.
Before you start
- Your site is added in the dashboard.
- You have an account in the tracker that can create work there.
In the dashboard, open your site and choose Relay. The setup has four steps, shown at the top: 1 Choose where, 2 Give access, 3 Pick the target, 4 Check it works.
1. Choose where
Pick where comments from this site should go:
| Destination | What a comment becomes |
|---|---|
| Linear | A task per comment. |
| Jira | An issue per comment in one project. |
| GitHub Issues | An issue per comment in one repository. |
| ClickUp | A task per comment in one list. |
| Asana | A task per comment in one project. |
| GitLab | An issue per comment in one project. |
| Plane | A work item per comment in one project. |
| Azure DevOps | A work item per comment in one project. |
| Trello | A card per comment in one list. |
| Notion | A page per comment in one database. |
The MCP tile is shown but cannot be chosen yet.
2. Give access
For Linear and GitHub, Passback asks for access in your browser, so there is no key to copy:
- Linear: click Connect with Linear and approve Passback in Linear. You come back to step 3.
- Jira: click Connect with Jira, choose your Atlassian site on Atlassian's screen and approve. Passback asks to read and write Jira work, read your user and keep access while you use it. There is no key to copy and no token form for Jira. You come back to step 3.
- GitHub Issues and GitHub pull requests: click Install the GitHub App, choose the account and the repositories Passback may use, and install. GitHub may then ask you once to authorize Passback; that confirms the installation is yours. You come back to step 3.
- GitLab: the address is optional: leave it empty for gitlab.com, or type the address you open a self-managed GitLab at, starting with https:// and with nothing after the host name (it must be reachable from the internet). Then an access token: a personal, project or group access token with the api scope, for a user with at least the Reporter role in the project. On gitlab.com: Preferences, then Access tokens.
- ClickUp: a personal API token. In ClickUp, click your avatar, then Settings, then Apps, and under API Token click Generate. The token starts with pk_ and does not expire; it can file into every List your ClickUp account can open.
- Asana: a personal access token from the Asana developer console (create one under Personal access tokens). Passback files each task as the person the token belongs to, so create it in an account that can add tasks to the project; a dedicated Asana user keeps the author neutral.
- Plane: first the workspace slug, the name in your Plane address; then an API key from Plane, Profile settings, API tokens.
- Azure DevOps: first the organization name, the part after
dev.azure.com/in your Azure DevOps address; then a personal access token from Azure DevOps, User settings, Personal access tokens, New token. Choose your organization and give the token only two scopes, Work Items (Read & write) and Project and Team (Read). Use an account made for this, because a token acts as the person who created it and stops working when it expires or is revoked; when that happens, paste a new one and save again. Azure DevOps Services only, not Azure DevOps Server. - Trello: there is no approval button; you paste two values. First the API key: in Trello open
trello.com/apps/admin, create a Power-Up (it is only the place Trello issues keys from; you do not publish it), open its Trello Auth tab and choose Generate a new API Key. Then the token: on the same page click Token, allow access and copy the token it shows; it lets Passback read and write your Trello account, so keep it secret. - Notion: an integration secret. In Notion, create an internal integration (Settings, Connections, Develop or manage integrations) with the Read content and Insert content capabilities and paste its secret here; a personal access token also works. Then share the database with it: open the database, choose the ••• menu, then Connections, and add the integration. Passback sees only the databases shared this way.
To paste a key for Linear or GitHub instead, click Use a token instead:
- Linear: a personal API key from Linear, Settings, API.
- GitHub: a fine-grained token with Issues: read and write (or Pull requests: read and write) on the one repository.
Click Check the key. The key is checked against the tracker, stored sealed, and never shown again.
If a step fails, the screen says why:
| The screen says | What to do |
|---|---|
| The connection was cancelled. Try again, or use a token instead. | Click the button again and approve, or use a token. |
| Your GitHub organisation owner has to approve the Passback app first. Try again once they have. | Ask an owner of the GitHub organisation to approve the Passback app, then click Install the GitHub App again. |
| Your GitHub account cannot see that installation of the Passback app. Install it on an account you belong to. | Install the app on your own account or an organisation you are a member of. |
| Passback could not finish the connection. Try again, or use a token instead. | Try again; if it keeps failing, use a token. |
| The tracker rejected this key. | Check the key, paste it again and retry. For Trello, both the API key and the token are checked. |
| Plane has no workspace with that slug for this key. | Check the workspace slug in your Plane address. |
| Azure DevOps has no organization with that name for this token. | Check the organization name in your Azure DevOps address. |
| That GitLab address cannot be used. Give the address you open GitLab at, starting with https:// and with nothing after the host name. | Check the address: https://, no path, a host that is public. |
| Notion shows no database to this secret yet. In Notion, open the database, choose the ••• menu, then Connections, and add your integration. Then go back and check again. | Share the database with the integration in Notion, then click Check the key again. |
| Cannot reach the tracker. Try again. | Wait a moment and click Check the key again. |
| Too many attempts. Wait a minute. | Wait a minute, then retry. |
3. Pick the target
The screen shows which account the key belongs to. Then choose where the comments land:
- Linear: a team. A project is optional.
- Jira: first the Jira site, then a project. Both are required.
- GitHub Issues: a repository from the list, or type it as
owner/repo. - GitLab: a project from the list. The list shows the projects the token's user is at least a Reporter in.
- ClickUp: a List from the list. Each name shows its Space and Folder, for example Product / Sprints / Bugs, and starts with the Workspace name when your token reaches more than one Workspace. If your List is missing, the token's account cannot open it.
- Asana: a workspace, then a project in it. The list shows the workspaces and projects the token can see.
- Plane: a project.
- Azure DevOps: a project, then the work item type, Task (the default) or Bug; the type must exist in the project's process, and Passback says so when it does not.
- Trello: first a board, then a list on it; both are required, and only open boards and open lists are shown.
- Notion: a database from the list.
Jira Cloud only. Jira Data Center and Jira Server are not supported.
Click Save. If the screen says "This key cannot see that target.", the key has no access there: pick another target, or go back and use a key that can see it.
4. Check it works
A connected site shows Connected and a line that starts "Comments go to", followed by the tracker and the target.
Click File a test comment. Passback files one test comment in the tracker; when it says Filed., the link next to it opens what was created.
- File issues as shows on a Linear site connected with Connect with Linear. Issues are filed as Passback by default. Choose you to file them under your own Linear name: Linear asks you to approve again, then you pick the team and click Save. Choose Passback to switch back the same way.
- Change starts the setup again at step 1. The current connection keeps working until you save a new one.
- Remove asks first. After Remove integration, comments from this site stop reaching the tracker until you connect again. For a connection made with Connect with Linear, Remove also withdraws Passback's access in Linear. For a Jira connection, Remove forgets the connection in Passback; Atlassian has no way for an app to withdraw access, so to withdraw it, remove Passback from the connected apps of your Atlassian account. For an Azure DevOps connection, Remove forgets the token in Passback; to withdraw access, revoke the token in Azure DevOps. For a Trello connection, Remove forgets the key and the token in Passback; Passback cannot revoke a token at Trello, so to withdraw access, revoke the token in your Trello account.
Notion and done comments. Passback reads one thing back from Notion: whether the page still exists. A comment counts as done in Passback only when its page is archived or moved to the trash in Notion. A Done checkbox or a Status column in your database is not read.
From the command line
You can also connect a tracker without the dashboard. Sign in first with npx passback login, then run the connect command for your tracker in the project: linear, jira, github, gitlab, asana, clickup, plane, azure-devops, trello or notion. Trello needs --key <API key> --token <token>. Plane also needs --workspace <slug>. Azure DevOps also needs --workspace <organization> and takes --type bug or --type task (Task by default). GitLab also takes --url <https address> for a self-managed one. Jira takes no --key: the browser opens for you to approve Passback.
npx passback login
npx passback connect linear --key <key>
npx passback connect jira
npx passback connect asana --key <token>
npx passback connect asana --key <token> --to "Workspace / Project"
npx passback connect clickup --key <token>
npx passback connect plane --key <key> --workspace <slug>
npx passback connect azure-devops --key <token> --workspace <organization> --to <project> --type bug
npx passback connect trello --key <API key> --token <token>
npx passback connect notion --key <secret>
npx passback connect notion --key <secret> --to "Bugs"
npx passback connect github --key <key> --to owner/repo
npx passback connect gitlab --key <token>
npx passback connect gitlab --key <token> --url https://gitlab.example.com --to group/projectThe command checks the key, saves the destination, files one test comment and prints where comments go.
- With several teams, projects or repositories, the command lists them. Pass one with
--to <target>. For Jira, pick a site and project with--to "<site> / <KEY>". For Trello, pick a board and list with--to "<board> / <list>". --site <name>picks another site than the one named after the project folder.--jsonprints one JSON line per step, for agents.
One tracker per site. To send a second site's comments somewhere else, connect that site on its own.