Connect Jira to your factory

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.
• 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

1. Install the Warp app on your Jira site. In the Integrations page of the Oz 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. 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 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. 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 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:

   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.

   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 for the full syntax.

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

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:

• project_keys - Match work items in these Jira projects.
• keywords - Match assignment text that contains any of these words. Matching is case-insensitive.

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 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

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 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.

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

• A bound Jira user becomes the run’s creator, not its agent - Connect 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

• 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 the other ways to route work into a factory, see connecting your factory.