From 1c394f2b216ba95375527aa408e572cd3fb09c67 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 15 Aug 2026 16:54:30 -0700 Subject: [PATCH 1/6] docs(factories): document Jira integration Co-Authored-By: Warp Agent Co-Authored-By: Warp --- .../docs/factories/integrations/jira.mdx | 81 ++++++++++++++++++- 1 file changed, 77 insertions(+), 4 deletions(-) diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index e299a6dc..181d5bf8 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -1,9 +1,82 @@ --- -title: Jira integration +title: Connect a factory to Jira description: >- - Jira integration documentation for Warp Factories will be added in a follow-up PR. + Connect Jira Cloud to a factory so Rovo agent sessions route assignments to + the configured agent and return results in Jira. sidebar: - label: "Jira" + label: Jira +topic: factories --- -Jira integration documentation for Warp Factories will land in a follow-up PR. +Connect Jira Cloud to a factory so people can assign Jira work items to **Warp** through Rovo. Jira starts an agent session, a factory automation routes the assignment to its configured agent, and Jira displays the task status and result in the same Rovo session. + +## Before you connect + +* **Jira Cloud** - The integration supports Jira Cloud, not Jira Server or Data Center. +* **Jira site admin** - A site admin installs the Warp app on the Jira site and connects the installation to a Warp workspace. +* **Factory access** - You need a factory in the connected workspace and permission to update its definition. +* **Rovo agent access** - The **Warp** agent must be available for Jira work items on the connected site. + +The Jira app's authorization determines which site and projects Warp can access and what the configured agent can read or update. Automation filters only route assignments within that access. Project or keyword filters do not reduce the app's credential permissions. + +## Connect Jira and configure agent sessions + +1. Follow the [Jira integration setup](https://docs.warp.dev/platform/integrations/jira/#setup) through connecting Jira to your Warp workspace, then return to this page instead of following the label-triggered run steps. The Jira installation becomes available to factories in that Warp workspace. +2. Review or add the Jira agent-session automation with [factory definitions as code](../factory-as-code). When you select Jira projects during a supported factory creation flow, Warp seeds an enabled `agent_session_created` automation scoped to those project keys. You can extend the seeded definition in `automations/jira-agent-sessions/automation.md`. Otherwise, declare Jira for the factory and add the trigger in `automations//automation.md`. The `agent` field selects the factory agent that handles matching Jira assignments. + + The current control-room automation editor does not expose the Jira agent-session trigger. Configure this trigger in the version-controlled factory definition. + +```markdown title="automations/jira-assignment/automation.md" +--- +enabled: true +agent: foreman +triggers: + - provider: jira + event: agent_session_created + filter: + project_keys: [ENG] + keywords: [investigate, fix] +--- + +Handle the Jira assignment and return a concise result. +``` + +`ENG` is a Jira project key. The keyword values match assignment text without regard to letter case. `foreman` is the name of the declared factory agent that receives the work. + +3. Apply the factory definition, then assign or mention **Warp** on a Jira work item and include an instruction. Confirm that Jira creates the agent session and that the matching run appears for the automation. + +## The agent session trigger and filters + +Jira intake uses a single event, `agent_session_created`. It fires when someone assigns or mentions **Warp** on a Jira work item, and a matching factory automation routes that assignment to its configured agent. + +The `agent_session_created` filter accepts two fields: + +* **`project_keys`** - Match the work item's Jira project key. +* **`keywords`** - Match the assignment text, without regard to letter case. + +Both fields combine together, and multiple values in one field act as alternatives. Leave a field empty to match any value the connected installation can deliver. + +## Context, follow-ups, and outputs + +The first Rovo message gives the configured agent the assignment text and associated Jira work item. When the factory declares Jira as an integration, the agent can use the connected Jira context to read the issue, comments, and available workflow transitions. + +Further messages in the same Rovo agent session continue the same run, including a follow-up after the previous turn completes. This continuity belongs to the Rovo session. Separate sessions for the same Jira issue are not automatically one factory workstream. + +Jira displays whether the task is submitted, working, waiting for input, completed, failed, or canceled. When the run finishes, the Rovo session receives the agent's text result instead of automatic issue comments. + +While the run is active, the configured agent can perform authorized Jira actions such as reading or updating an issue, finding assignable users, assigning or unassigning an issue, posting or updating comments, changing workflow status, and adding or removing labels. Make those actions explicit in the automation instructions. Jira permissions and valid workflow transitions still apply. Pull request review and merge requirements remain repository or workflow policy. + +## Permissions and delivery caveats + +Grant the Jira app only the site and project access required for the factory's work. Restrict Rovo intake separately with project and keyword filters. The run executes as the agent selected by the matching automation, not as the Jira user who started the session. + +Atlassian can retry a Rovo message. Warp associates repeated delivery of the same message with one factory admission. Keep issue mutations duplicate-safe anyway: check current state before posting a comment, changing status, or adding a label, and make repeated actions harmless. + +## Troubleshooting + +* **Warp is unavailable in Jira** - Confirm the Warp app is installed on the Jira Cloud site. Open its **Configure** page and click **Connect to Warp** if the installation is not connected. +* **No run starts** - Confirm an enabled `agent_session_created` automation exists, its agent is available, and its project and keyword filters match the Rovo assignment. +* **The session has no result** - Check the matching automation's run to determine whether the configured agent is still working, waiting for input, or failed. +* **A Jira update fails** - Confirm the app can access the work item's project and perform the requested action or workflow transition. + +For other intake paths and provider boundaries, see [connecting your factory](../connect-your-factory). From c7340eaf74761f1d97da5af8bc687adaaf1ae3d8 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Sun, 16 Aug 2026 05:29:52 +0000 Subject: [PATCH 2/6] docs(factories): clarify Jira integration page Editorial pass for external readers: - Lead with the user flow in plain language instead of internal routing vocabulary - Restructure setup into three clean steps with the automation example nested under its step, and explain the example inline - Consolidate trigger/filter behavior into one section, removing repeated explanations of when the event fires and keyword case-insensitivity - Replace internal jargon (seeds, intake, factory admission, issue mutations) with plain wording - Surface the filters-vs-access caveat as a caution callout and group permissions/reliability notes into a scannable list - Align title and headers with the sibling Linear page; use root-relative link for the platform setup page Co-Authored-By: Warp --- .../docs/factories/integrations/jira.mdx | 99 +++++++++---------- 1 file changed, 49 insertions(+), 50 deletions(-) diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index 181d5bf8..2c257707 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -1,82 +1,81 @@ --- -title: Connect a factory to Jira +title: Connect Jira to your factory description: >- - Connect Jira Cloud to a factory so Rovo agent sessions route assignments to - the configured agent and return results in Jira. + Connect Jira Cloud to a factory so work items assigned to Warp in Rovo start + factory runs and return results in Jira. sidebar: label: Jira topic: factories --- -Connect Jira Cloud to a factory so people can assign Jira work items to **Warp** through Rovo. Jira starts an agent session, a factory automation routes the assignment to its configured agent, and Jira displays the task status and result in the same Rovo session. +Connect Jira Cloud to your factory so your team can start factory work without leaving Jira. When someone assigns or mentions **Warp** on a work item, Jira starts a Rovo agent session, a factory automation routes the request to the agent you chose, and the same session shows progress and the final result. -## Before you connect +## Prerequisites -* **Jira Cloud** - The integration supports Jira Cloud, not Jira Server or Data Center. -* **Jira site admin** - A site admin installs the Warp app on the Jira site and connects the installation to a Warp workspace. -* **Factory access** - You need a factory in the connected workspace and permission to update its definition. -* **Rovo agent access** - The **Warp** agent must be available for Jira work items on the connected site. +* **Jira Cloud** - The integration supports Jira Cloud only, not Jira Server or Data Center. +* **A Jira site admin** - Installing the Warp app on a Jira site and connecting it to a Warp workspace requires site admin permissions. +* **A factory** - You need a factory in the connected workspace and permission to edit its [definition](../factory-as-code). +* **Rovo access** - The **Warp** agent must be available on your Jira site so people can assign or mention it on work items. -The Jira app's authorization determines which site and projects Warp can access and what the configured agent can read or update. Automation filters only route assignments within that access. Project or keyword filters do not reduce the app's credential permissions. +## Connect Jira and add an automation -## Connect Jira and configure agent sessions +1. Install the Warp app and connect it to your Warp workspace by following the [Jira integration setup](/platform/integrations/jira/#setup). Stop once the workspace is connected and return here; the label-triggered run steps on that page don't apply to factories. The connected installation is available to every factory in the workspace. -1. Follow the [Jira integration setup](https://docs.warp.dev/platform/integrations/jira/#setup) through connecting Jira to your Warp workspace, then return to this page instead of following the label-triggered run steps. The Jira installation becomes available to factories in that Warp workspace. -2. Review or add the Jira agent-session automation with [factory definitions as code](../factory-as-code). When you select Jira projects during a supported factory creation flow, Warp seeds an enabled `agent_session_created` automation scoped to those project keys. You can extend the seeded definition in `automations/jira-agent-sessions/automation.md`. Otherwise, declare Jira for the factory and add the trigger in `automations//automation.md`. The `agent` field selects the factory agent that handles matching Jira assignments. +2. Add a Jira automation to your factory definition. The control room's automation editor doesn't include the Jira trigger, so configure it with [definitions as code](../factory-as-code): declare the `jira` integration for the factory, then create an automation that listens for the `agent_session_created` event. The `agent` field names the factory agent that handles matching requests. - The current control-room automation editor does not expose the Jira agent-session trigger. Configure this trigger in the version-controlled factory definition. + ```markdown title="automations/jira-assignment/automation.md" + --- + enabled: true + agent: foreman + triggers: + - provider: jira + event: agent_session_created + filter: + project_keys: [ENG] + keywords: [investigate, fix] + --- -```markdown title="automations/jira-assignment/automation.md" ---- -enabled: true -agent: foreman -triggers: - - provider: jira - event: agent_session_created - filter: - project_keys: [ENG] - keywords: [investigate, fix] ---- - -Handle the Jira assignment and return a concise result. -``` - -`ENG` is a Jira project key. The keyword values match assignment text without regard to letter case. `foreman` is the name of the declared factory agent that receives the work. + Handle the Jira assignment and return a concise result. + ``` -3. Apply the factory definition, then assign or mention **Warp** on a Jira work item and include an instruction. Confirm that Jira creates the agent session and that the matching run appears for the automation. + With this automation, the agent named `foreman` handles sessions for work items in the `ENG` project whose assignment text contains `investigate` or `fix`. -## The agent session trigger and filters + If you selected Jira projects when you created the factory, Warp already added this automation at `automations/jira-agent-sessions/automation.md`, scoped to those projects. Edit that file instead of creating a second automation. -Jira intake uses a single event, `agent_session_created`. It fires when someone assigns or mentions **Warp** on a Jira work item, and a matching factory automation routes that assignment to its configured agent. +3. Apply the definition, then test it: assign or mention **Warp** on a work item and include an instruction. Jira starts an agent session, and the run appears under the matching automation in your factory. -The `agent_session_created` filter accepts two fields: +## Filter which sessions start runs -* **`project_keys`** - Match the work item's Jira project key. -* **`keywords`** - Match the assignment text, without regard to letter case. +All Jira work reaches the factory through a single event, `agent_session_created`, which fires when someone assigns or mentions **Warp** on a work item. A session starts a run only when it matches an enabled automation. Use the trigger's `filter` to narrow what matches: -Both fields combine together, and multiple values in one field act as alternatives. Leave a field empty to match any value the connected installation can deliver. +* **`project_keys`** - Match work items in these Jira projects. +* **`keywords`** - Match assignment text that contains any of these words. Matching is case-insensitive. -## Context, follow-ups, and outputs +A session must match every field you set; within a field, any listed value is a match. Omit a field to match everything. -The first Rovo message gives the configured agent the assignment text and associated Jira work item. When the factory declares Jira as an integration, the agent can use the connected Jira context to read the issue, comments, and available workflow transitions. +:::caution +Filters decide which sessions start runs; they don't limit access. The Warp app's authorization in Jira controls which site and projects agents can read and update, so grant the app only the access the factory's work requires. +::: -Further messages in the same Rovo agent session continue the same run, including a follow-up after the previous turn completes. This continuity belongs to the Rovo session. Separate sessions for the same Jira issue are not automatically one factory workstream. +## What happens during a run -Jira displays whether the task is submitted, working, waiting for input, completed, failed, or canceled. When the run finishes, the Rovo session receives the agent's text result instead of automatic issue comments. +The agent starts with the assignment text and the work item it came from. When the factory declares Jira as an integration, the agent can also read the work item's details, comments, and available workflow transitions. -While the run is active, the configured agent can perform authorized Jira actions such as reading or updating an issue, finding assignable users, assigning or unassigning an issue, posting or updating comments, changing workflow status, and adding or removing labels. Make those actions explicit in the automation instructions. Jira permissions and valid workflow transitions still apply. Pull request review and merge requirements remain repository or workflow policy. +Jira shows the task's status as it progresses: submitted, working, waiting for input, completed, failed, or canceled. Replies in the same Rovo session continue the same run, even after the agent finishes a turn, so you can answer questions or add direction mid-task. A new session on the same work item starts a separate run. -## Permissions and delivery caveats +When the run finishes, the agent posts its result in the Rovo session. It doesn't comment on the work item unless you ask it to. The agent can act in Jira when asked: update the work item, post or edit comments, change workflow status, add or remove labels, or reassign it. State the actions you want in the automation instructions or the assignment; Jira permissions and valid workflow transitions apply to everything the agent does. -Grant the Jira app only the site and project access required for the factory's work. Restrict Rovo intake separately with project and keyword filters. The run executes as the agent selected by the matching automation, not as the Jira user who started the session. +## Permissions and reliability -Atlassian can retry a Rovo message. Warp associates repeated delivery of the same message with one factory admission. Keep issue mutations duplicate-safe anyway: check current state before posting a comment, changing status, or adding a label, and make repeated actions harmless. +* **Runs act as the factory agent** - A run executes as the agent selected by the automation, not as the Jira user who started the session. +* **Repeated deliveries don't repeat runs** - Atlassian occasionally redelivers a Rovo message, and Warp treats redelivered copies as one request. Prefer instructions that check state before writing anyway, such as looking for an existing comment or label before adding one. +* **Code changes follow repository policy** - The Jira connection doesn't grant code access. Pull request review and merge requirements come from your repositories and factory workflow. ## Troubleshooting -* **Warp is unavailable in Jira** - Confirm the Warp app is installed on the Jira Cloud site. Open its **Configure** page and click **Connect to Warp** if the installation is not connected. -* **No run starts** - Confirm an enabled `agent_session_created` automation exists, its agent is available, and its project and keyword filters match the Rovo assignment. -* **The session has no result** - Check the matching automation's run to determine whether the configured agent is still working, waiting for input, or failed. -* **A Jira update fails** - Confirm the app can access the work item's project and perform the requested action or workflow transition. +* **Warp is unavailable in Jira** - Confirm the Warp app is installed on the Jira Cloud site. On the app's **Configure** page, click **Connect to Warp** if the installation isn't connected to a workspace. +* **No run starts** - Confirm an enabled `agent_session_created` automation exists, its agent is available, and its project and keyword filters match the assignment. +* **The session shows no result** - Open the matching automation's run to see whether the agent is still working, waiting for input, or failed. +* **A Jira update fails** - Confirm the app can access the work item's project and that the requested action or workflow transition is valid. -For other intake paths and provider boundaries, see [connecting your factory](../connect-your-factory). +For the other ways to route work into a factory, see [connecting your factory](../connect-your-factory). From e9f5ada4e30ad6bbf44b0e1ef1dca241cb01d414 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Sun, 16 Aug 2026 05:33:02 +0000 Subject: [PATCH 3/6] docs(factories): center Jira page on Warp, not Rovo Reduce Rovo mentions from six to one. The remaining mention is a recognition pointer in prerequisites (Jira lists the Warp agent among Atlassian's Rovo agents); everywhere else the actors are Warp and the factory agent, and sessions are just agent sessions. Co-Authored-By: Warp --- src/content/docs/factories/integrations/jira.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index 2c257707..ef73dbb0 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -1,21 +1,21 @@ --- title: Connect Jira to your factory description: >- - Connect Jira Cloud to a factory so work items assigned to Warp in Rovo start - factory runs and return results in Jira. + Connect Jira Cloud to a factory so work items assigned to Warp start factory + runs and return results in Jira. sidebar: label: Jira topic: factories --- -Connect Jira Cloud to your factory so your team can start factory work without leaving Jira. When someone assigns or mentions **Warp** on a work item, Jira starts a Rovo agent session, a factory automation routes the request to the agent you chose, and the same session shows progress and the final result. +Connect Jira Cloud to your factory so your team can start factory work without leaving Jira. When someone assigns or mentions **Warp** on a work item, Jira starts an agent session, a factory automation routes the request to the agent you chose, and the same session shows progress and the final result. ## Prerequisites * **Jira Cloud** - The integration supports Jira Cloud only, not Jira Server or Data Center. * **A Jira site admin** - Installing the Warp app on a Jira site and connecting it to a Warp workspace requires site admin permissions. * **A factory** - You need a factory in the connected workspace and permission to edit its [definition](../factory-as-code). -* **Rovo access** - The **Warp** agent must be available on your Jira site so people can assign or mention it on work items. +* **The Warp agent in Jira** - The **Warp** agent must be available on your Jira site so people can assign or mention it on work items. Jira lists it among Atlassian's Rovo agents. ## Connect Jira and add an automation @@ -61,14 +61,14 @@ Filters decide which sessions start runs; they don't limit access. The Warp app' The agent starts with the assignment text and the work item it came from. When the factory declares Jira as an integration, the agent can also read the work item's details, comments, and available workflow transitions. -Jira shows the task's status as it progresses: submitted, working, waiting for input, completed, failed, or canceled. Replies in the same Rovo session continue the same run, even after the agent finishes a turn, so you can answer questions or add direction mid-task. A new session on the same work item starts a separate run. +Jira shows the task's status as it progresses: submitted, working, waiting for input, completed, failed, or canceled. Replies in the same agent session continue the same run, even after the agent finishes a turn, so you can answer questions or add direction mid-task. A new session on the same work item starts a separate run. -When the run finishes, the agent posts its result in the Rovo session. It doesn't comment on the work item unless you ask it to. The agent can act in Jira when asked: update the work item, post or edit comments, change workflow status, add or remove labels, or reassign it. State the actions you want in the automation instructions or the assignment; Jira permissions and valid workflow transitions apply to everything the agent does. +When the run finishes, the result appears in the agent session. The agent doesn't comment on the work item unless you ask it to. The agent can act in Jira when asked: update the work item, post or edit comments, change workflow status, add or remove labels, or reassign it. State the actions you want in the automation instructions or the assignment; Jira permissions and valid workflow transitions apply to everything the agent does. ## Permissions and reliability * **Runs act as the factory agent** - A run executes as the agent selected by the automation, not as the Jira user who started the session. -* **Repeated deliveries don't repeat runs** - Atlassian occasionally redelivers a Rovo message, and Warp treats redelivered copies as one request. Prefer instructions that check state before writing anyway, such as looking for an existing comment or label before adding one. +* **Repeated deliveries don't repeat runs** - Jira occasionally delivers the same message more than once, and Warp treats the copies as one request. Prefer instructions that check state before writing anyway, such as looking for an existing comment or label before adding one. * **Code changes follow repository policy** - The Jira connection doesn't grant code access. Pull request review and merge requirements come from your repositories and factory workflow. ## Troubleshooting From 711b0f41538bdc73896d26262bbcf226a087caae Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Sun, 16 Aug 2026 22:42:34 +0000 Subject: [PATCH 4/6] docs(factories): address Jira page review feedback - Inline the app install and workspace connection steps instead of bouncing readers to the platform setup page mid-procedure; keep that page as a supplementary deep link and plainly note that its warp-agent label flow is for standalone cloud agents, not factories. - Note the agent runs in the cloud and link cloud agent session sharing for watching the full run from the factory. - Drop the repeated-deliveries bullet (internal dedup detail with no user action). - Reword the code-access bullet: connecting Jira grants no repository access, and agent PRs go through the usual review process. Co-Authored-By: Warp --- .../docs/factories/integrations/jira.mdx | 22 ++++++++++++------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index ef73dbb0..375c3030 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -7,6 +7,7 @@ sidebar: label: Jira topic: factories --- +import { VARS } from '@data/vars'; Connect Jira Cloud to your factory so your team can start factory work without leaving Jira. When someone assigns or mentions **Warp** on a work item, Jira starts an agent session, a factory automation routes the request to the agent you chose, and the same session shows progress and the final result. @@ -19,9 +20,13 @@ Connect Jira Cloud to your factory so your team can start factory work without l ## Connect Jira and add an automation -1. Install the Warp app and connect it to your Warp workspace by following the [Jira integration setup](/platform/integrations/jira/#setup). Stop once the workspace is connected and return here; the label-triggered run steps on that page don't apply to factories. The connected installation is available to every factory in the workspace. +1. Install the Warp app on your Jira site. In the Integrations page of the {VARS.WEB_APP}, find Jira and click **Set up**, then click **Get app** on the Atlassian installation page and install the app on your Jira Cloud site. -2. Add a Jira automation to your factory definition. The control room's automation editor doesn't include the Jira trigger, so configure it with [definitions as code](../factory-as-code): declare the `jira` integration for the factory, then create an automation that listens for the `agent_session_created` event. The `agent` field names the factory agent that handles matching requests. +2. Connect the installation to your Warp workspace. In Jira, open **Manage apps** and open the Warp app's **Configure** page, then click **Connect to Warp** and sign in to Warp if prompted. The page shows **Connected to Warp** when the connection succeeds, and every factory in the workspace can then use it. + + The [Jira integration setup](/platform/integrations/jira/#setup) covers installation in more detail. The `warp-agent` label flow on that page starts standalone cloud agent runs; factories skip the label and start runs through an automation instead. + +3. Add a Jira automation to your factory definition. The control room's automation editor doesn't include the Jira trigger, so configure it with [definitions as code](../factory-as-code): declare the `jira` integration for the factory, then create an automation that listens for the `agent_session_created` event. The `agent` field names the factory agent that handles matching requests. ```markdown title="automations/jira-assignment/automation.md" --- @@ -42,7 +47,7 @@ Connect Jira Cloud to your factory so your team can start factory work without l If you selected Jira projects when you created the factory, Warp already added this automation at `automations/jira-agent-sessions/automation.md`, scoped to those projects. Edit that file instead of creating a second automation. -3. Apply the definition, then test it: assign or mention **Warp** on a work item and include an instruction. Jira starts an agent session, and the run appears under the matching automation in your factory. +4. Apply the definition, then test it: assign or mention **Warp** on a work item and include an instruction. Jira starts an agent session, and the run appears under the matching automation in your factory. ## Filter which sessions start runs @@ -59,17 +64,18 @@ Filters decide which sessions start runs; they don't limit access. The Warp app' ## What happens during a run -The agent starts with the assignment text and the work item it came from. When the factory declares Jira as an integration, the agent can also read the work item's details, comments, and available workflow transitions. +The agent runs in the cloud and starts with the assignment text and the work item it came from. When the factory declares Jira as an integration, the agent can also read the work item's details, comments, and available workflow transitions. + +Jira shows the task's status as it progresses: submitted, working, waiting for input, completed, failed, or canceled. For more than status updates, open the run under the matching automation in your factory: [cloud agent session sharing](/platform/viewing-cloud-agent-runs/) shows the full run, including every command, log, and output, in real time or after the run finishes. -Jira shows the task's status as it progresses: submitted, working, waiting for input, completed, failed, or canceled. Replies in the same agent session continue the same run, even after the agent finishes a turn, so you can answer questions or add direction mid-task. A new session on the same work item starts a separate run. +Replies in the same agent session continue the same run, even after the agent finishes a turn, so you can answer questions or add direction mid-task. A new session on the same work item starts a separate run. When the run finishes, the result appears in the agent session. The agent doesn't comment on the work item unless you ask it to. The agent can act in Jira when asked: update the work item, post or edit comments, change workflow status, add or remove labels, or reassign it. State the actions you want in the automation instructions or the assignment; Jira permissions and valid workflow transitions apply to everything the agent does. -## Permissions and reliability +## Permissions * **Runs act as the factory agent** - A run executes as the agent selected by the automation, not as the Jira user who started the session. -* **Repeated deliveries don't repeat runs** - Jira occasionally delivers the same message more than once, and Warp treats the copies as one request. Prefer instructions that check state before writing anyway, such as looking for an existing comment or label before adding one. -* **Code changes follow repository policy** - The Jira connection doesn't grant code access. Pull request review and merge requirements come from your repositories and factory workflow. +* **Jira access doesn't include code access** - Connecting Jira lets agents read and update Jira work items, nothing more. Agents get repository access from the factory itself, and pull requests they open go through your usual review and merge process. ## Troubleshooting From 159fabe9893476267004f48adc42a600e05ca05c Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Mon, 17 Aug 2026 08:24:37 +0000 Subject: [PATCH 5/6] docs(factories): address Jira page review feedback (round 2) - Document the automation editor's Jira trigger (Add trigger > Jira > Agent session created), now that the control room editor supports it alongside GitHub, GitLab, Linear, and Slack triggers. Keep definitions as code as the alternative path. - Correct the access caution: Jira access is workspace-wide today (no per-team or per-project scoping exists yet), so drop the inaccurate suggestion that the Warp app's Jira authorization can be scoped by project. - Remove the now-false claim that a new session on the same work item always starts a separate run. - Rewrite the Permissions bullet: the Jira user who starts a session must connect their Jira account to Warp before a run starts (new user-binding gate); the run still executes as the automation's agent, not as that Jira user. Co-Authored-By: Warp --- src/content/docs/factories/integrations/jira.mdx | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index 375c3030..6c260778 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -26,7 +26,11 @@ Connect Jira Cloud to your factory so your team can start factory work without l The [Jira integration setup](/platform/integrations/jira/#setup) covers installation in more detail. The `warp-agent` label flow on that page starts standalone cloud agent runs; factories skip the label and start runs through an automation instead. -3. Add a Jira automation to your factory definition. The control room's automation editor doesn't include the Jira trigger, so configure it with [definitions as code](../factory-as-code): declare the `jira` integration for the factory, then create an automation that listens for the `agent_session_created` event. The `agent` field names the factory agent that handles matching requests. +3. Add a Jira trigger to an automation. In the control room, open the factory's **Automations** tab, then open an automation (or create a new one). Click **Add trigger**, choose **Jira**, and select **Agent session created**. Set **Projects** and, optionally, **Keywords** to scope which sessions start a run, then set the automation's agent to the one that should handle matching requests. + + If you selected Jira projects when you created the factory, Warp already added an automation scoped to those projects; edit that automation instead of creating a second one. + + Prefer definitions as code? Declare the `jira` integration for the factory and add an `agent_session_created` trigger to the automation file directly; see [definitions as code](../factory-as-code) for the full syntax. ```markdown title="automations/jira-assignment/automation.md" --- @@ -45,9 +49,7 @@ Connect Jira Cloud to your factory so your team can start factory work without l With this automation, the agent named `foreman` handles sessions for work items in the `ENG` project whose assignment text contains `investigate` or `fix`. - If you selected Jira projects when you created the factory, Warp already added this automation at `automations/jira-agent-sessions/automation.md`, scoped to those projects. Edit that file instead of creating a second automation. - -4. Apply the definition, then test it: assign or mention **Warp** on a work item and include an instruction. Jira starts an agent session, and the run appears under the matching automation in your factory. +4. Save the automation — or apply the definition if you used definitions as code — then test it: assign or mention **Warp** on a work item and include an instruction. Jira starts an agent session, and the run appears under the matching automation in your factory. ## Filter which sessions start runs @@ -59,7 +61,7 @@ All Jira work reaches the factory through a single event, `agent_session_created A session must match every field you set; within a field, any listed value is a match. Omit a field to match everything. :::caution -Filters decide which sessions start runs; they don't limit access. The Warp app's authorization in Jira controls which site and projects agents can read and update, so grant the app only the access the factory's work requires. +Filters decide which sessions start runs; they don't limit access. The Warp app's authorization applies to your whole connected Jira site: every team in the workspace can trigger runs against any project the app can reach, regardless of a filter's `project_keys`. Warp doesn't yet offer a way to scope Jira access by team or project. ::: ## What happens during a run @@ -68,13 +70,13 @@ The agent runs in the cloud and starts with the assignment text and the work ite Jira shows the task's status as it progresses: submitted, working, waiting for input, completed, failed, or canceled. For more than status updates, open the run under the matching automation in your factory: [cloud agent session sharing](/platform/viewing-cloud-agent-runs/) shows the full run, including every command, log, and output, in real time or after the run finishes. -Replies in the same agent session continue the same run, even after the agent finishes a turn, so you can answer questions or add direction mid-task. A new session on the same work item starts a separate run. +Replies in the same agent session continue the same run, even after the agent finishes a turn, so you can answer questions or add direction mid-task. When the run finishes, the result appears in the agent session. The agent doesn't comment on the work item unless you ask it to. The agent can act in Jira when asked: update the work item, post or edit comments, change workflow status, add or remove labels, or reassign it. State the actions you want in the automation instructions or the assignment; Jira permissions and valid workflow transitions apply to everything the agent does. ## Permissions -* **Runs act as the factory agent** - A run executes as the agent selected by the automation, not as the Jira user who started the session. +* **The Jira user connects their own account first** - The person who assigns or mentions **Warp** must [connect their Jira account to Warp](/platform/integrations/jira/#connecting-your-jira-account-to-warp) before their session can start a run; an unconnected user gets a prompt to connect instead of a run starting. A run still executes as the agent selected by the automation, not as that Jira user. * **Jira access doesn't include code access** - Connecting Jira lets agents read and update Jira work items, nothing more. Agents get repository access from the factory itself, and pull requests they open go through your usual review and merge process. ## Troubleshooting From c60d39fe9bc9ea017569153bfb470dfe692a798c Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Mon, 17 Aug 2026 08:38:41 +0000 Subject: [PATCH 6/6] docs(factories): fix four accuracy issues from adversarial review - Add the missing per-factory Jira connection step (Settings > Jira > Connect/Install, select projects, Enable). Without it, the automation editor's Add trigger > Jira entry stays a disabled not-connected item (confirmed via AutomationEditor.tsx/TriggerMenu.tsx/ JiraIntegrationConnect.tsx and the editor's own test suite). - Correct the access caution: project_keys does control whether a given automation fires (provider_jira.go's evalFilter), it just isn't an access boundary across teams in the same workspace. Left the last sentence about no team/project scoping untouched. - Rewrite the Permissions bullet: a bound Jira actor becomes the run's creator/ActorUserID (automation_dispatch_jira.go), while the automation's agent remains the ExecutionPrincipal either way. - Make the definitions-as-code alternative self-contained (factory.yaml integration declaration + automation file path) instead of depending on the still-stubbed factory-as-code page. Co-Authored-By: Warp --- src/content/docs/factories/integrations/jira.mdx | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index 6c260778..525301f1 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -26,11 +26,13 @@ Connect Jira Cloud to your factory so your team can start factory work without l The [Jira integration setup](/platform/integrations/jira/#setup) covers installation in more detail. The `warp-agent` label flow on that page starts standalone cloud agent runs; factories skip the label and start runs through an automation instead. -3. Add a Jira trigger to an automation. In the control room, open the factory's **Automations** tab, then open an automation (or create a new one). Click **Add trigger**, choose **Jira**, and select **Agent session created**. Set **Projects** and, optionally, **Keywords** to scope which sessions start a run, then set the automation's agent to the one that should handle matching requests. +3. Connect Jira to your factory. Connecting the workspace in step 2 makes Jira available to every factory in it, but each factory still needs its own connection: in the factory's **Settings** tab, find **Jira** and click **Connect** (or **Install** if the workspace itself isn't connected yet). Select the Jira projects that should trigger this factory, then click **Enable**. This declares the `jira` integration for the factory — without it, **Jira** in the automation editor's **Add trigger** menu stays a disabled "not connected" entry that only links back to this step. + +4. Add a Jira trigger to an automation. In the control room, open the factory's **Automations** tab, then open an automation (or create a new one). Click **Add trigger**, choose **Jira**, and select **Agent session created**. Set **Projects** and, optionally, **Keywords** to scope which sessions start a run, then set the automation's agent to the one that should handle matching requests. If you selected Jira projects when you created the factory, Warp already added an automation scoped to those projects; edit that automation instead of creating a second one. - Prefer definitions as code? Declare the `jira` integration for the factory and add an `agent_session_created` trigger to the automation file directly; see [definitions as code](../factory-as-code) for the full syntax. + Prefer definitions as code? Declare the `jira` integration in the factory's `factory.yaml` (`integrations: [{type: jira}]`), then add a file under `automations/` — for example `automations/jira-assignment/automation.md` — with an `agent_session_created` trigger: ```markdown title="automations/jira-assignment/automation.md" --- @@ -47,9 +49,9 @@ Connect Jira Cloud to your factory so your team can start factory work without l Handle the Jira assignment and return a concise result. ``` - With this automation, the agent named `foreman` handles sessions for work items in the `ENG` project whose assignment text contains `investigate` or `fix`. + With this automation, the agent named `foreman` handles sessions for work items in the `ENG` project whose assignment text contains `investigate` or `fix`. Commit and push the files to apply them; see [definitions as code](../factory-as-code) for the full syntax. -4. Save the automation — or apply the definition if you used definitions as code — then test it: assign or mention **Warp** on a work item and include an instruction. Jira starts an agent session, and the run appears under the matching automation in your factory. +5. Save the automation — or apply the definition if you used definitions as code — then test it: assign or mention **Warp** on a work item and include an instruction. Jira starts an agent session, and the run appears under the matching automation in your factory. ## Filter which sessions start runs @@ -61,7 +63,7 @@ All Jira work reaches the factory through a single event, `agent_session_created A session must match every field you set; within a field, any listed value is a match. Omit a field to match everything. :::caution -Filters decide which sessions start runs; they don't limit access. The Warp app's authorization applies to your whole connected Jira site: every team in the workspace can trigger runs against any project the app can reach, regardless of a filter's `project_keys`. Warp doesn't yet offer a way to scope Jira access by team or project. +Filters like `project_keys` decide whether *your* automation starts a run; they aren't an access boundary. A Jira event is evaluated against every team's automations in the connected workspace, so another team's automation with a broader or different filter can still start its own run on the same work item. Warp doesn't yet offer a way to scope Jira access by team or project. ::: ## What happens during a run @@ -76,7 +78,7 @@ When the run finishes, the result appears in the agent session. The agent doesn' ## Permissions -* **The Jira user connects their own account first** - The person who assigns or mentions **Warp** must [connect their Jira account to Warp](/platform/integrations/jira/#connecting-your-jira-account-to-warp) before their session can start a run; an unconnected user gets a prompt to connect instead of a run starting. A run still executes as the agent selected by the automation, not as that Jira user. +* **A bound Jira user becomes the run's creator, not its agent** - [Connect your Jira account to Warp](/platform/integrations/jira/#connecting-your-jira-account-to-warp) so a session you start is attributed to you; an unconnected account gets a prompt to connect instead of a run starting. Either way, the run executes as the agent selected by the automation, not as that Jira user. * **Jira access doesn't include code access** - Connecting Jira lets agents read and update Jira work items, nothing more. Agents get repository access from the factory itself, and pull requests they open go through your usual review and merge process. ## Troubleshooting