Link a project to an issue tracker
A linked project starts tasks from its tracker's issues, and its tasks can link to an issue by hand. Every Jira, Linear and Backlog connection works the same way.
Who can do this: anyone who can edit the project links it. Connecting the tracker itself needs an Owner or Admin: see Jira, Linear or Backlog.
Link the project
- Open the project's Settings tab, section Issue trackers.
- Select Add link.
- Pick the Connection, then one or more Tracker projects (a Jira project, a Linear team, a Backlog project).
- Select Add.
Each linked connection is one row, listing its tracker projects. Edit changes them; Remove drops the connection after Remove link? asks. Tasks already linked to an issue keep their link.
No projects picked on a row means the connection is linked but none of its tracker projects are: select Edit and pick some. No tracker linked. means the project links none yet; No tracker connected. means your organization has no connection yet.
An Owner or Admin can also link from the connection's Mapping tab, under Issue trackers. It lists the project each tracker project starts tasks in.
Choose where tracker-started tasks land
Several Jaah projects can link the same tracker project. All of them can pick its issues, but a task an issue starts lands in one: the one marked Starts tasks. The first project to link it gets the mark.
To move the mark to this project, select Make primary beside the tracker project. Make primary shows only when another project shares it. Removing the primary link passes the mark to the oldest remaining one.
Choose whether imported tasks start on their own
Each linked connection has Auto-start imported tasks. It saves as soon as you change it.
- On: a task an issue starts in this project runs at once.
- Off: the task waits on the board as a draft until someone starts it. Jaah comments on the issue with a link to the draft.
A new link starts with it off. Links made before the setting existed keep it on.
Pick an issue for a task
On a new task, or a task you edit:
- In From issue, type an issue key or words from its title.
- Pick the issue. The list holds issues of the tracker projects this project links, from every linked connection.
The issue's title and description fill the Description. If it already has text, Replace or Keep mine asks first. Save or Go links the task to the issue; clearing From issue and saving removes the link.
From issue shows only when the project links at least one tracker project. On a phone it moves into Advanced.
The task's page shows the linked issue in its header, such as Jira OAM-12. Select it to open the issue. A task the tracker started shows its issue the same way, and its link can't be changed.
Moving a task to a project that doesn't link the issue's tracker project removes a link picked by hand.
What Jaah posts on the issue
When an issue's task waits as a draft (Auto-start imported tasks is off), Jaah says so once, with a link to the task. A draft you link by hand posts nothing.
From the moment a linked task starts, Jaah posts on its issue:
- a "started" comment with a link to the task;
- a line when work starts, and when the task waits for an answer;
- each question the task asks;
- the pull request's link;
- the task's outcome.
When the task is done, Jaah moves the issue to the connection's done state, once no other task linked to the issue is still at work. A task with an open pull request waits for it to merge; a task done without one, marked done by hand or closed as already done, moves the issue at once. A task started from the issue and one linked by hand are told the same.
It works the other way too. When someone moves the issue to the done state in the tracker, every task linked to it is completed, even one that is still running, and Jaah posts its outcome. Moving the issue out of the done state again changes nothing in Jaah. To turn this off, clear Done in Jira completes the task (or Linear, or Backlog) on the connection's Mapping tab.
- Linked after it finished: Jaah posts the task's outcome only.
- Linked to another issue: the old issue hears nothing more. The new one gets the "started" comment, open questions, the pull request and the outcome, and progress from then on.
Who can read issues
Anyone who can create tasks in a linked project can read, through From issue, the titles and descriptions of issues in its linked tracker projects that the connection's account can read. Give a connection only the tracker access its projects need.
A Jira connection moved from a project's Jira secret
A project that had a Jira secret before trackers was moved to a Jira connection, already linked. Picking issues and posting back work at once. If its row says No projects picked, select Edit and pick the Jira projects. A personal secret, or one Jaah could not read, was not moved: link a connection by hand. Issues start tasks only after a Jira site admin adds a webhook: an Owner or Admin selects New webhook URL on the connection's page, and the URL and secret it shows go into the webhook as in step 6 of Start tasks from Jira.