Skip to main content

Start tasks from Jira

Connect your Jira Cloud site once, and an issue assigned to Jaah, mentioning Jaah or carrying the jaah label starts a task in the Jaah project you mapped. Jaah comments on the issue as the task goes, and moves it to Done when its pull request merges.

Who can do this: connecting needs an Owner or Admin of your organization in Jaah, and a Jira site admin. Jira Server and Data Center are not supported. Using Linear instead? See Start tasks from Linear.

There are two ways to connect. Pick one per site:

Jaah's Jira appA Jaah account
What you set up in JiraInstall the app, paste a codeAn Atlassian account, an API token and a webhook
Who Jaah acts asThe app, shown as JaahThat account
Uses an Atlassian seatNoYes
Start a task by@Jaah in a comment, or the start labelAssigning, @Jaah in a comment, or the start label

Connect with Jaah's Jira app​

Jaah's Jira app sends your site's issue events to Jaah and lets Jaah comment on and move issues. It sends nothing until you enter the code from Jaah.

  1. In Jaah, open Settings › Integrations › Issue trackers and select Add tracker. Choose Jira as the Tracker and Forge app as the Sign-in. Enter your Jira address, such as acme.atlassian.net, as the Site, then select Next.

  2. The Jira app step lists what to do, in order. Select Install Jaah’s Jira app, then, as a Jira site admin, pick your site and confirm the install.

  3. Copy the Code. Jaah shows it only now, and it works once, within 24 hours.

  4. Select Connect to Jaah in Jira. It opens the app's page in your site's Jira settings. Paste the code into Code and select Connect.

    No link? Jaah doesn't know your site yet, such as when Site was left empty. In Jira (not Atlassian Administration), open Settings › Apps, then Jaah in the left menu.

  5. Back in Jaah, State turns to Claimed by itself and Next turns on. Select Next, then map your Jira projects and finish, as in steps 7 and 8 below.

The app reads and writes issues in every project of the site, but starts tasks only in projects you map. To disconnect, uninstall the app in Jira (Settings › Apps › Manage apps) and select Delete on the tracker in Jaah.

Connect with a Jaah account​

Jaah acts in Jira as an ordinary Atlassian account. Use a dedicated one, named Jaah, so its comments and assignments are easy to tell apart.

  1. In Atlassian, invite an account for Jaah to your site and give it access to the Jira projects it should work in (Browse projects, Assignable user, Add comments, Transition issues).
  2. Sign in as that account and create an API token at id.atlassian.com, under Security › API tokens.
  3. In Jaah, open Directory, then Secrets, select Add secret and choose Jira. Enter your site's address, the Jaah account's email and the token.
  4. Open Settings › Integrations › Issue trackers and select Add tracker. Choose Jira as the Tracker and API token as the Sign-in, pick the secret as the Secret (Site fills from it), and select Next.
  5. The Webhook step lists what to do, with a URL and a Secret shown once. Copy both.
  6. Select WebHooks in Jira (or, in Jira, open Settings › System › WebHooks) and select Create a WebHook:
    • paste the URL into URL and the Secret into Secret;
    • under Events, tick Issue › created, Issue › updated and Comment › created;
    • optionally limit the events with JQL, such as project in (OAM, WEB);
    • select Create. Creating a webhook needs a Jira site admin.
  7. Back in Jaah, select Next. On Projects, pick each Jira project (Add another row) and the Jaah project its issues start tasks in, then select Next.
  8. On Labels & people, change the Start label or Done state if you want, then select Finish.

Map more Jira projects later on the connection's Mapping tab, or link from each project: see Link a project to an issue tracker.

The connection's automation appears under Automations. It files a coder task, Full Auto, in the mapped project.

Start a task​

In an issue of a mapped project, do one of these:

  • Assign the issue to Jaah.
  • Write @Jaah in a comment, such as @Jaah fix the typo. The rest of the comment becomes the task's instruction. Type it as plain text, or mention the Jaah account if Jira offers one.
  • Add the jaah label, or the start label you set on Mapping.

The task gets the issue's summary, description and latest comments, and links back to the issue. An issue has one live task: assigning it again, or labelling it while its task works, starts nothing new.

To stop the task, unassign Jaah or remove the label.

If the connection signs in with your own Atlassian account, assigning an issue to yourself starts nothing: add the label or write @Jaah in a comment instead. The same goes for a Jira automation rule that runs as that account.

With Jaah's Jira app, comment or use the label: Jira can't assign issues to an app.

What happens on the issue​

Jaah comments on the issue as the task goes: see What Jaah posts on the issue.

When the task is done, Jaah moves the issue to Done, or to the Done state you set on Mapping: when its pull request merges, or at once for a task done without one. The status must be reachable from the issue's current status in the project's workflow. Moving the issue to that status yourself completes its tasks in Jaah.

Reply on the issue to answer a question or add to the task. Only members of your Jaah organization whose Atlassian email matches their Jaah email, and who may act on the task, are heard. On an API-token connection, the Jira account it signs in with counts as the person who connected it.

Troubleshooting​

SymptomWhat to do
The app's page in Jira says "Jaah refused the code"The code is used, older than 24 hours or mistyped, or another connection holds the site. Delete the tracker, add the tracker again and paste the new code.
Nothing happens when you assign the issueCheck Events on the connection's page. No event: the URL or events of the webhook are wrong, or its JQL leaves the project out. Reason invalid signature: the Secret in Jira is not the one Jaah showed; delete the tracker, add the tracker again and update the webhook.
The event's outcome is Filtered, "is not a member of this organization"The person's Atlassian email does not match a member of your organization, or their profile hides it. On an API-token connection, the Jira account the connection signs in with counts as the person who connected it. For anyone else, turn on Non-members can start tasks on People, or add them to Jaah.
The event's outcome is Filtered, "no Jaah project is mapped"Map the issue's Jira project on Mapping.
A comment with @Jaah starts nothingCheck that @Jaah is not part of a longer word or address, such as @jaahbot. On the issue of a task already at work, the comment goes to that task instead.
The issue does not move to DoneRead the error on the connection's Events. "No transition moves…": the done state is not reachable from the issue's current status. Add that step to the Jira workflow, or set Done state to a status the workflow reaches.