Skip to content
gritz

Jira

The Jira integration turns activity on Jira Cloud issues into events: new comments, added labels and new assignees. Routing rules then decide what each event does: wake the task working on the issue, create a new task for it, or nothing.

It has two halves:

  • A Jira webhook, pointed at your organisation’s Atlassian webhook URL, is how Jira sends gritz events. It is set up once per gritz organisation.
  • Your Atlassian account, linked on Settings → Account, tells gritz which events are yours, so your organisation’s member-only rules act on them.

The server must have the Atlassian integration configured; operators, see Atlassian.

Section titled “Link your Atlassian account”

On Settings → Account, in the Atlassian Account card, click Link Atlassian Account and approve the request on Atlassian. gritz only asks to read your profile; it records your Atlassian account ID and name.

Once linked, your comments, labels and assignments on Jira count as yours in every organisation you are a member of. Unlink removes the link.

Connect Jira

Section titled “Connect Jira”

1. Generate the webhook secret

Section titled “1. Generate the webhook secret”

On Settings → Organisation, the Atlassian Webhook card shows the organisation’s webhook URL:

https://gritz.dev/webhook/atlassian?org=<org-id>

Click Generate Secret. gritz rejects every Jira event for the organisation until it has a secret. Regenerate Secret replaces it; the old one stops working at once, so update the webhook in Jira straight after.

2. Create the webhook in Jira

Section titled “2. Create the webhook in Jira”

As a Jira administrator, open Settings → System → WebHooks and create a webhook:

  • URL: the webhook URL from the card, including ?org=.
  • Secret: the secret from the card.
  • Events: under Comment, created; under Issue, updated. Add a JQL filter if you only want some projects’ issues.

Jira signs each delivery with the secret, and gritz checks the signature before it reads the event, so a delivery with a missing or wrong signature is refused with 403.

The URL names one gritz organisation. To send the same Jira site’s events to two organisations, create a webhook for each.

Which events reach your organisation

Section titled “Which events reach your organisation”

Every event sent to your organisation’s webhook belongs to your organisation, whoever caused it:

  • If the person who caused it has linked their Atlassian account and is a member, your organisation’s member-only rules can act on it. It also goes to the other organisations they are a member of.
  • Otherwise, only your public rules act on it.

Events

Section titled “Events”
Jira webhook Event type Its URL
Comment created Jira: Issue Comment the comment, as …/browse/PROJ-123?focusedCommentId=10001
Issue updated, with labels added Jira: Label Added the issue, as …/browse/PROJ-123
Issue updated, with a new assignee Jira: Issue Assigned the issue

Other updates, such as a status change or an edited description, are ignored. One update can send two events: assigning an issue and adding a label in the same edit sends both. Adding several labels at once sends one Label Added event with all of them, and a label condition holds if any of them matches. Unassigning an issue sends nothing.

A comment’s URL points at the comment, but gritz matches it to its issue. So a task with a subscribed link to https://your-domain.atlassian.net/browse/PROJ-123 gets every comment on PROJ-123.

Jira identifies people by account ID rather than by name, and so do the user, mention and assignee attributes. Enter the bare ID, such as 5b10ac8d82e05b22cc7d4ef5, not the [~accountid:…] form Jira uses in comment text. The account ID is at the end of the URL of the person’s Jira profile. See Event types for every attribute.

Each event on a task’s timeline has a description, such as Ada Lovelace commented on PROJ-123, its URL and, for comments, the comment’s text. gritz doesn’t post anything back to Jira.

Examples

Section titled “Examples”

Wake the task working on an issue whenever a member comments on it:

  • Event type: Jira: Issue Comment
  • Wake up linked tasks: on

Start a task for every issue in one project that is labelled gritz:

  • Event type: Jira: Label Added
  • Conditions: label equals gritz, url prefix https://your-domain.atlassian.net/browse/PROJ-
  • Create a task: on, with a runner, a workspace and a prompt
  • Wake up linked tasks: on

Start a task when an issue is assigned to a bot account, whoever assigns it:

  • Event type: Jira: Issue Assigned
  • Conditions: assignee equals <the bot's account ID>
  • Create a task: on
  • Public: on

The agent needs its own Jira credentials, from its workspace, to read the issue or reply to it.