> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira Automation (Auto-Pickup)

> Configure Genesis to automatically pick up Jira tickets when they are assigned, change status, or receive a comment, using either inbound webhooks (push) or scheduled polling (pull).

## Overview

This page is the **second step** in the Jira setup flow:

1. [Setup Jira API Parameters](/docs/Setup/Setup-Jira-API-Params) — generate a Jira API token and save the connection.
2. **Jira Automation (Auto-Pickup)** — *this page* — have Genesis automatically start work on tickets that match your rules.
3. [Jira Connector Tools](/docs/Genbot-Toolkit/Jira-Connector-Tools) — for ad-hoc, manual Jira operations from inside an agent thread.

Once Jira credentials are configured, Genesis can **automatically start a bot working on a Jira issue** when something specific happens to that issue — typically when it is assigned to a dedicated `Genesis` Jira identity, transitions to a particular status, or receives an `@genesis` comment.

There are two ways Genesis hears about Jira issue changes, and you can use either or both:

* **Webhook (push)** — Jira calls Genesis at `POST /api/jira/webhook` whenever a subscribed event happens. Lowest latency. Requires that your Jira instance can reach the Genesis URL.
* **Polling (pull)** — Genesis runs a scheduled `Jira Ticket Poller` Flow that searches Jira for recently updated issues and applies your trigger rules. Works in any network topology, including air-gapped Jira where inbound webhooks are not viable.
* **Hybrid** — both at once. Webhooks deliver normal events; polling acts as a safety net for missed deliveries.

In a Databricks App, Genesis cannot receive inbound webhooks, so the Automation
tab offers **Polling** only. If a saved Jira automation configuration uses
`webhook` or `hybrid`, opening the tab switches its form to `polling` and shows
a notice; save the form to apply polling. Other deployments retain all three
ingestion modes.

In all modes, Genesis only **starts agent work** when an issue both belongs to your monitored scope and matches your configured trigger rules. Each issue gets a stable Genesis thread, so follow-up events on the same ticket resume the existing thread instead of starting over.

<Note>
  All Jira automation and worker controls are admin-scoped. You need Genesis admin access (or shared connection-management permissions) to see the **Automation** and **Genesis worker** tabs in the Jira connection modal on **Config -> Connections**. Open **+ New Connection**, choose **Jira** under **Dev Tools**, or edit an existing Jira connection to switch tabs.
</Note>

## Prerequisites

Before configuring automation, make sure all of the following are true:

1. A **shared** Jira connection has been saved in Genesis with valid credentials. See [Setup Jira API Parameters](/docs/Setup/Setup-Jira-API-Params). Personal connections cannot be selected for automation — the poller and webhook intake run without the setup user's session.
2. You know the Jira project keys Genesis should monitor (for example `OPS`, `DATA`).
3. You have decided which Genesis bot should pick up tickets. The default is `Eve`.
4. (Recommended) You have an Atlassian service account that Genesis can use as its dedicated Jira identity, with **Jira product access** and **assignable** in every monitored project.
5. (Webhook mode only) Your Jira instance can reach the Genesis backend over HTTPS.

## Ingestion modes

You configure the ingestion mode per Genesis deployment from the **Automation** tab in the Jira connection modal on **Config -> Connections** (or via the `jira_automation_setup_action` tool from chat).

### Polling (pull) — recommended default

In `polling` mode Genesis owns a scheduled **Jira Ticket Poller** Flow. On each run Genesis:

1. Builds a JQL query scoped to your `project_keys` (or your custom `issue_jql_filter`).
2. Restricts to issues `updated` since the last successful poll, with a small overlap so updates near the boundary are not missed.
3. Runs the search through your selected Jira connection (capped by `poll_max_results`).
4. For each returned issue, applies the configured trigger rules.
5. Deduplicates so the same matching condition does not retrigger.
6. For new matches, opens or resumes the issue's stable Genesis thread, posts an acknowledgement comment in Jira, optionally transitions the issue to `status_on_pickup`, and dispatches the configured bot to begin work.

The Jira acknowledgement says **“Genesis is on it.”** for a new pickup and
**“Genesis is back on it.”** when resuming work. When Genesis has a public web
address, the comment links to the Jira-filtered **Work** page and the agent's
thread. If this is a dashboard RCA investigation, it also links to the
investigation view when that link is available.

Polling is the safest default — it works even when Jira cannot make outbound HTTP calls to Genesis, and the Flow is visible in the scheduler so operators can monitor last run state.

### Webhook (push)

Genesis exposes `POST /api/jira/webhook` as a public-but-signed endpoint. When you enable webhook mode, Genesis shows the URL to copy into Jira admin. After Jira sends a request:

1. Genesis validates the optional `X-Hub-Signature` header against your configured `webhook_secret`.
2. Genesis applies the same trigger rules as polling (project scope, JQL filter, status / assignee / comment matches).
3. Matching events open or resume the issue's stable Genesis thread and dispatch the bot.

Use webhook mode when your Jira can reach Genesis reliably; otherwise prefer polling or hybrid.

### Hybrid

`hybrid` runs both: webhooks handle normal traffic and polling backfills anything missed. This is the most resilient configuration if your environment supports it.

## Trigger types

Whichever ingestion mode you pick, **trigger rules** decide which issues actually wake up a bot. Set `trigger_type` to one of:

| Value | Genesis picks up an issue when... |
| - | - |
| **`assignment`** | The issue's assignee matches an entry in `trigger_on_assignees` (typically the dedicated Genesis service-worker identity). |
| **`status`** | The issue's status matches an entry in `trigger_on_statuses` (for example `Ready for Genesis`). |
| **`status_or_assignment`** | Either of the above matches. |
| **`comment_keyword`** | A new Jira comment contains a keyword from `trigger_on_comment_keywords` (for example `@genesis`) or @-mentions a tracked assignee. |
| **`hybrid`** *(default)* | Any of the above matches. Recommended for most clients. |

<Tip>
  For most teams, `hybrid` with `trigger_on_assignees` set to the Genesis service-worker identity and `trigger_on_comment_keywords = ["@genesis", "genesis"]` produces the best UX: assigning the ticket to **Genesis** kicks off work, and a later comment like `@genesis please revise this` resumes the same Genesis thread.
</Tip>

## Setup workflow

<Steps>
  <Step title="Create a dedicated Genesis Jira identity">
    In Atlassian Administration, create a **service account** named `Genesis` (or invite a regular user, if you prefer). Grant it **Jira product access** and make sure it is **assignable** in every project that Genesis should monitor. Generate a Jira **API token** for that identity — Genesis will use it to author comments and status transitions as `Genesis`.
  </Step>

  <Step title="Save the Jira connection">
    Confirm the shared Jira connection has been saved in Genesis with credentials that can read/write the target projects. See [Setup Jira API Parameters](/docs/Setup/Setup-Jira-API-Params).
  </Step>

  <Step title="Configure the Genesis worker">
    Open **Config -> Connections**, open the Jira connection modal (**+ New Connection** -> **Jira** under **Dev Tools**, or edit an existing Jira connection), and select the **Genesis worker** tab. Fill in:

    * **Worker label**: typically `@genesis`.
    * **Worker email**: the email of the Atlassian service account.
    * **Expected display name**: `Genesis`.
    * **Projects to validate**: the Jira project keys Genesis should monitor.
    * **Genesis worker API token**: the API token from step 1.

    Save, then click **Validate worker**. Genesis resolves the Jira `accountId`, confirms the worker is assignable in every listed project, and binds that identity into assignment-trigger automation.
  </Step>

  <Step title="Configure automation rules">
    In the same Jira connection modal, select the **Automation** tab and set:

    * **Enable Jira automation**: on.
    * **Auto-pick up tickets**: on.
    * **Jira connection**: the saved Jira connection.
    * **Detection mode**: `polling`, `webhook`, or `hybrid`.
    * **Genesis bot ID**: usually `Eve`.
    * **Project keys** (or **JQL filter**): the search scope.
    * **Trigger type** and the relevant trigger lists (assignees, statuses, comment keywords).
    * **Status on pickup / needs info / done** (optional, recommended).

    Save. If polling or hybrid is selected, Genesis creates or updates the **Jira Ticket Poller** Flow and shows it as `scheduled`.
  </Step>

  <Step title="(Webhook or hybrid only) Register the Jira webhook">
    Copy the **Jira webhook URL** shown in the Automation tab. In Jira admin, create a webhook that points at it. If you set a `webhook_secret` in Genesis, configure the same secret in Jira. Scope the webhook to the monitored projects and subscribe to:

    * issue created
    * issue updated
    * comment created
    * comment updated
  </Step>

  <Step title="Verify end-to-end">
    Assign a real ticket in a monitored project to the Genesis Jira identity. Within one poll interval (or immediately, in webhook mode), Genesis should open or resume the issue's thread, post a Jira comment acknowledging pickup, optionally transition the status, and start work.
  </Step>
</Steps>

## Automation parameter reference

These fields are saved on the **Automation** tab. Defaults are applied when a field is left blank.

| **Field** | **Type** | **Default** | **Notes** |
| - | - | - | - |
| **`enabled`** | Boolean | `false` | Master switch. When off, Genesis ignores all Jira events regardless of other settings. |
| **`ingestion_mode`** | String | `polling` | One of `polling`, `webhook`, `hybrid`. |
| **`auto_pickup`** | Boolean | `true` | When `false`, Genesis records that an issue matched but does **not** dispatch the bot. Use this to "dry-run" rules. |
| **`jira_connection_id`** | String | empty | The saved **shared** Jira connection that Genesis uses for Jira API calls (for example `jira.shared`). Personal connections are unsupported for automation. If empty, Genesis falls back to the default Jira connection when it is shared. |
| **`bot_id`** | String | `Eve` | The Genesis bot that picks up matched issues. |
| **`project_keys`** | Array of strings | `[]` | Jira project keys Genesis monitors (for example `["OPS", "DATA"]`). Ignored when `issue_jql_filter` is set. |
| **`issue_jql_filter`** | String | empty | Custom JQL used as the search scope. When set, it **overrides** `project_keys`. Useful for narrow scopes like `project = OPS AND labels = genesis-eligible`. |
| **`trigger_type`** | String | `hybrid` | One of `assignment`, `status`, `status_or_assignment`, `comment_keyword`, `hybrid`. See [Trigger types](#trigger-types). |
| **`trigger_on_assignees`** | Array of strings | `[]` | Atlassian `accountId`s, emails, or display names that mean "Genesis should take this." Populated automatically by **Validate worker** for the dedicated Genesis identity. |
| **`trigger_on_statuses`** | Array of strings | `[]` | Jira status names that should trigger pickup, for example `["Ready for Genesis"]`. |
| **`trigger_on_comment_keywords`** | Array of strings | `["@genesis", "genesis"]` | Case-insensitive substrings; a new comment matching any keyword triggers pickup (subject to `trigger_type`). |
| **`status_on_pickup`** | String | empty | Optional Jira status Genesis transitions the issue to as soon as it picks up the work, for example `In Progress`. |
| **`status_on_needs_info`** | String | empty | Optional Jira status Genesis sets when the bot is waiting for user input. |
| **`status_on_done`** | String | empty | Optional Jira status Genesis sets when the bot finishes, for example `Done`. |
| **`webhook_secret`** | String (secret) | empty | Optional shared secret. When set, Genesis verifies the `X-Hub-Signature` header on each webhook delivery. Always set this in production. |
| **`poll_interval_seconds`** | Integer | `60` | How often the polling Flow runs. Minimum `30`. |
| **`poll_lookback_minutes`** | Integer | `5` | Used on the first poll and for manual "poll now" runs. Steady-state runs resume from the last successful poll cursor with a short overlap. Minimum `1`. |
| **`poll_max_results`** | Integer | `50` | Maximum issues Genesis inspects per poll (maximum `200`). |

The following fields are **read-only telemetry** that Genesis writes itself; you do not edit them, but you can monitor them for operations:

| **Field** | **Meaning** |
| - | - |
| **`poller_flow_id`** / **`poller_job_id`** / **`poller_schedule_status`** | Identity and status of the scheduled `Jira Ticket Poller` Flow. |
| **`poller_last_run_at`** / **`poller_next_run_at`** | When the Flow last ran and when it is expected to run next. |
| **`last_successful_poll_at`** | Cursor used by the next poll to bound `updated >=`. |
| **`last_poll_started_at`** | Start time of the most recent poll attempt. |
| **`last_poll_error`** | Last error message from polling, or empty if the most recent run succeeded. |

## Genesis worker parameter reference

These fields are saved on the **Genesis worker** tab. They define the Atlassian identity Genesis acts as.

| **Field** | **Type** | **Default** | **Notes** |
| - | - | - | - |
| **`worker_label`** | String | `@genesis` | Friendly label shown in Genesis UI; it does not have to match the Atlassian display name. |
| **`worker_email`** | String | empty | The Atlassian service-account email (or invited user's email). |
| **`worker_display_name`** | String | `Genesis` | The display name expected in Jira. Validation tolerates display-name-only matches when Jira hides emails. |
| **`worker_account_id`** | String | empty | Resolved Atlassian `accountId`. Genesis fills this in on **Validate worker**. |
| **`worker_api_token`** | String (secret) | empty | API token belonging to the Genesis identity. Without this, Jira write-backs (comments, transitions) are authored by the shared integration credential rather than `Genesis`. |
| **`project_keys`** | Array of strings | `[]` | Projects in which the worker must be assignable. **Validate worker** checks each one. |
| **`auto_bind_assignment_trigger`** | Boolean | `true` | When `true` (default), a successful **Validate worker** automatically adds the resolved identity to `trigger_on_assignees`. |
| **`org_id`** | String | empty | Atlassian org ID. Only needed when using **Provision worker** to invite a regular user via the Atlassian Admin API. |
| **`admin_api_key`** | String (secret) | empty | Atlassian admin API key. Same caveat as `org_id`. |
| **`additional_groups`** | Array of strings | `[]` | Optional Atlassian groups the invited worker should be added to (used by **Provision worker**). |
| **`send_notification`** | Boolean | `true` | Whether **Provision worker** sends an Atlassian invite email. |
| **`invitation_message`** | String | empty | Custom message included with the Atlassian invite email. |

<Note>
  The **recommended** path is a client-managed Atlassian **service account** plus **Validate worker**. Use **Provision worker** (with `org_id` + `admin_api_key`, or with an admin-capable Jira credential) only when you specifically want Genesis to invite a regular Atlassian user account.
</Note>

## End-to-end production sequence

Use this for the typical enterprise rollout.

1. Save the shared Jira connection in Genesis using the client Jira URL, integration email, and API token.
2. In Atlassian Administration, create a service account named `Genesis`.
3. Grant that service account Jira product access and any group/project roles needed for it to be assignable in the target projects.
4. Generate a Jira API token for that service account.
5. In Genesis, open **Config -> Connections**, open the Jira connection modal, select the **Genesis worker** tab, and save the worker label, service-account email, expected display name, project keys, and the worker API token.
6. Click **Validate worker** and confirm Genesis reports a resolved account ID, assignable status in the target projects, and assignment-trigger automation bound.
7. Select the **Automation** tab, choose the ingestion mode (polling, webhook, or hybrid), set the trigger type and lists, and save.
8. (Webhook or hybrid only) Configure the Jira webhook in Jira admin using the URL and secret shown in Genesis.
9. Confirm the **Jira Ticket Poller** Flow status shows `scheduled` (polling/hybrid only).
10. Assign a real ticket in a monitored project to `Genesis` and confirm Genesis opens or resumes the issue thread, reads the issue, and posts back into Jira as `Genesis`.

## What end users see

After setup, the day-to-day workflow for a Jira user is:

1. Create or update a Jira ticket in a monitored project.
2. Assign the ticket to the Jira identity `Genesis` (or trigger via status / `@genesis` comment, depending on configuration).
3. Genesis automatically starts or resumes work in the configured bot's thread.
4. Genesis posts questions, progress updates, and outcomes back to the Jira issue.
5. Follow-up comments such as `@genesis please revise for executives` resume the same Genesis thread instead of starting over.

## Troubleshooting

### Ticket assigned to Genesis but nothing happens

Check, in order:

1. Jira automation is **enabled**.
2. The issue's project is included in `project_keys`, or it satisfies `issue_jql_filter`.
3. **Validate worker** succeeded and `trigger_on_assignees` includes the resolved Genesis `accountId`.
4. The assignee in Jira is the actual resolved Genesis identity, not a similarly named human.
5. In polling mode, the polling Flow status is `scheduled` and `last_poll_error` is empty.
6. The configured `bot_id` exists and is online.

### Genesis replied in Jira as the shared integration user instead of Genesis

The worker API token is missing, invalid, or not saved. Save (or rotate) the **Genesis worker API token** in the worker panel and validate again.

### `@genesis` comments do not wake Genesis

1. `trigger_type` includes comment wakeups (`comment_keyword` or `hybrid`).
2. `trigger_on_comment_keywords` includes `@genesis`.
3. In polling mode, the comment was posted after the last successful poll cursor and lies within the inspected recent comments.
4. The comment was posted by a human, not by Genesis itself (Genesis ignores its own automation comments).

### Worker validates but is not assignable

The Jira identity exists but lacks project permissions. Fix the Jira-side access model (project role / group membership) and re-run **Validate worker**.

### Webhook deliveries are rejected

If `webhook_secret` is set in Genesis, Jira must send the matching value via the `X-Hub-Signature` header. Re-paste the secret on both sides, then redeliver from Jira's webhook log.

## Observing automation activity

Every detection, claim, dispatch, suppressed duplicate, and failure is recorded
See [Requests](/docs/User-Guide/Work-Center) for Jira activity.

The **Automation** tab in the Jira connection modal includes a **View requests →** link to the Requests page.

## Related pages

* [Setup Jira API Parameters](/docs/Setup/Setup-Jira-API-Params)
* [Jira Connector Tools](/docs/Genbot-Toolkit/Jira-Connector-Tools)
* [Connections](/docs/Setup/Connections)
* [Flows / Scheduler](/docs/User-Guide/Flows)