Add initial Jira integration docs#281
Conversation
Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds an initial Jira integration page and wires it into the integrations landing page and sidebar. The structure is mostly in the right place, and the security pass did not identify code or configuration security findings, but the new page has user-facing terminology and requirements issues that should be fixed before publishing.
Concerns
- The page uses the user-facing phrase "Oz agents" / "Oz agent runs," which the docs terminology guide explicitly says to avoid in favor of "agents" or "cloud agent runs."
- The requirements understate integration access requirements compared with the existing integration docs: they omit credits and the precise eligible plan set.
- Troubleshooting exposes the internal
JiraEnabledflag name and sends users to a Warp team admin, who may not have a way to verify that internal gate.
Verdict
Found: 0 critical, 2 important, 1 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>
Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>
Co-authored-by: Jason Keung <jason.keungg@gmail.com>
Co-authored-by: Jason Keung <jason.keungg@gmail.com>
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR adds an initial Jira integration docs page, wires it into the Integrations overview, and adds it to the Platform integrations sidebar. The page covers the early-access flow, but the requirements section omits prerequisites users need before Jira-triggered agents can work on code.
Concerns
- The Jira page should list the required cloud environment and GitHub authorization prerequisites alongside plan, credit, and Jira admin requirements.
- One setup sentence should clarify that the automatic connection behavior applies to a single Warp workspace, not a Jira workspace.
Verdict
Found: 0 critical, 1 important, 1 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com> Co-authored-by: Jason Keung <jason.keungg@gmail.com>
There was a problem hiding this comment.
Docs review — Jira integration (verification round)
Reviewed against the integration/feature-doc conventions and verified the open questions against warp-server, specifically the simple_integrations framework the Jira integration will build on. Solid initial page: correct placement under platform/integrations/, sidebar + index wired correctly, no broken links, and npm run build passing per the PR description. Verdict: approve with changes.
Included in my review:
- 5 one-click suggestions on
jira.mdx: identity/attribution requirement (+*bullets), where to configure defaults (step 3), a run-monitoring cross-link, a troubleshooting error-code tip (+*bullets), and a Related pages section. - 3 questions for things I couldn't confirm from code: plan/credits + Enterprise eligibility, how the Jira label-adder maps to a Warp identity, and the "our community" link target.
- 1 structural note (not a clean one-click suggestion): section order should be Requirements → Setup → How to start a run.
Nit that can't be inline (the line isn't in this PR's diff): in index.mdx the intro "from tools like Slack and Linear" could include Jira — ..., [Linear](/platform/integrations/linear/), and [Jira](/platform/integrations/jira/).
Co-Authored-By: Oz oz-agent@warp.dev
| - **Jira Cloud** - Jira Server and Data Center are not supported. | ||
| - **Warp team and eligible plan** - Your team must be on a **Build, Max, or Business** plan with at least **20 credits** available, or on an **Enterprise** plan with a team credit pool. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details. | ||
| - **A configured cloud environment** - Agents run inside an [environment](/platform/environments/) that includes the repositories and dependencies they need. Configure a Jira-specific default environment or confirm your team's default configuration includes one. | ||
| - **GitHub authorization** - Warp needs access to your repositories to clone code and open pull requests. Authorize the Warp GitHub app before using the integration for code tasks. | ||
| - **Jira site admin** - Installing the Oz app in Jira requires site admin permissions. |
There was a problem hiding this comment.
* to match the Slack/Linear pages and the docs templates.
Confirmed against the simple_integrations framework in warp-server (router/handlers/external/linear.go, IntegrationList/CreateEditModal.tsx): the integration matches the external user to a Warp account by email and runs as that user, using their GitHub authorization to open PRs. A missing match returns external_authentication_required.
| - **Jira Cloud** - Jira Server and Data Center are not supported. | |
| - **Warp team and eligible plan** - Your team must be on a **Build, Max, or Business** plan with at least **20 credits** available, or on an **Enterprise** plan with a team credit pool. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details. | |
| - **A configured cloud environment** - Agents run inside an [environment](/platform/environments/) that includes the repositories and dependencies they need. Configure a Jira-specific default environment or confirm your team's default configuration includes one. | |
| - **GitHub authorization** - Warp needs access to your repositories to clone code and open pull requests. Authorize the Warp GitHub app before using the integration for code tasks. | |
| - **Jira site admin** - Installing the Oz app in Jira requires site admin permissions. | |
| * **Jira Cloud** - Jira Server and Data Center are not supported. | |
| * **Warp team and eligible plan** - Your team must be on a **Build, Max, or Business** plan with at least **20 credits** available, or on an **Enterprise** plan with a team credit pool. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details. | |
| * **A configured cloud environment** - Agents run inside an [environment](/platform/environments/) that includes the repositories and dependencies they need. Configure a Jira-specific default environment or confirm your team's default configuration includes one. | |
| * **GitHub authorization** - Warp needs access to your repositories to clone code and open pull requests. Authorize the Warp GitHub app before using the integration for code tasks. | |
| * **A matching Warp identity** - Warp matches the Jira user who adds the label to a Warp account by email, and the agent runs as that user, using their GitHub authorization to open pull requests. If no Warp account matches the email, the run fails with an [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) error. | |
| * **Jira site admin** - Installing the Oz app in Jira requires site admin permissions. |
|
|
||
| #### 3. (Optional) Configure the default environment, model, and harness | ||
|
|
||
| In your integration settings, you can configure the default environment, model, and harness that Oz will use for runs triggered from Jira. If none is set, Oz uses your team's default configuration. |
There was a problem hiding this comment.
💡 [SUGGESTION] Confirmed accurate against SimpleIntegrationConfig (model/types/simple_integrations.go) and the Oz web app integration form (IntegrationList/CreateEditModal.tsx) — environment, model, and harness are all configurable. Just add where these settings live.
| In your integration settings, you can configure the default environment, model, and harness that Oz will use for runs triggered from Jira. If none is set, Oz uses your team's default configuration. | |
| In the [Oz web app](https://oz.warp.dev/integrations), open your Jira integration to set the default [environment](/platform/environments/), model, and harness Oz uses for Jira-triggered runs. If you don't set these, Oz uses your team's default configuration. |
|
|
||
| Add the label **`oz-agent`** to any Jira issue. Oz will pick it up, post a comment to let you know it's started, and begin working through the task using the issue title, description, and recent comments as context. | ||
|
|
||
| When the run finishes, Oz posts a summary comment to the issue with links to any pull requests or branches it created, along with a link to the full conversation in Warp. |
There was a problem hiding this comment.
💡 [SUGGESTION] Point readers to where they can watch runs, matching the Slack/Linear pages (which link the Agent Management Panel / All tab).
| When the run finishes, Oz posts a summary comment to the issue with links to any pull requests or branches it created, along with a link to the full conversation in Warp. | |
| When the run finishes, Oz posts a summary comment to the issue with links to any pull requests or branches it created, along with a link to the full conversation in Warp. To track runs across your team, open the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app, where Jira-triggered runs appear in the **All** tab. |
| If Oz doesn't respond after adding the label, check that: | ||
|
|
||
| - The Oz app is installed and the workspace is connected (see the app's Configure screen in Jira). | ||
| - The issue is in Jira Cloud (not Server or Data Center). |
There was a problem hiding this comment.
💡 [SUGGESTION] Switch to * bullets and add an error-code tip, consistent with the Slack/Linear/GitHub Actions pages. Codes confirmed in platformerrors.go; integration runs surface errors back to the source as comments (error_reporting.go).
| If Oz doesn't respond after adding the label, check that: | |
| - The Oz app is installed and the workspace is connected (see the app's Configure screen in Jira). | |
| - The issue is in Jira Cloud (not Server or Data Center). | |
| If Oz doesn't respond after adding the label, check that: | |
| * The Oz app is installed and the workspace is connected (see the app's Configure screen in Jira). | |
| * The issue is in Jira Cloud (not Server or Data Center). | |
| :::tip | |
| When a Jira-triggered run can't start, Oz posts an error comment on the issue. Common codes: | |
| * [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) - your plan doesn't support integrations. | |
| * [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) - no Warp account matches the Jira user's email, or GitHub isn't authorized. | |
| * [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/) - the integration was removed or disabled. | |
| ::: |
| - The Oz app is installed and the workspace is connected (see the app's Configure screen in Jira). | ||
| - The issue is in Jira Cloud (not Server or Data Center). | ||
|
|
||
| For other issues, reach out to your Warp contact or post in our community. |
There was a problem hiding this comment.
💡 [SUGGESTION] The page currently dead-ends — add a Related pages section for cross-linking (docs guideline + parity with Slack/Linear). Keeps line 60 and appends the section.
| For other issues, reach out to your Warp contact or post in our community. | |
| For other issues, reach out to your Warp contact or post in our community. | |
| --- | |
| ### Related pages | |
| * [Integrations overview](/platform/integrations/) - How environments and integrations work together. | |
| * [Slack](/platform/integrations/slack/) and [Linear](/platform/integrations/linear/) - Other chat- and issue-triggered integrations. | |
| * [Managing cloud agents](/platform/managing-cloud-agents/) - Monitor Jira-triggered runs across your team. | |
| * [Environments](/platform/environments/) - Configure where agents run. |
There was a problem hiding this comment.
Now that we've confirmed the canonical community is Slack (see the resolved question on this line), I've folded the community-link fix into this suggestion. Apply this version instead of the original above — it changes our community to the Slack link and adds the Related pages section in one apply.
| For other issues, reach out to your Warp contact or post in our community. | |
| For other issues, reach out to your Warp contact or join the [Warp community on Slack](https://go.warp.dev/join-preview). | |
| --- | |
| ### Related pages | |
| * [Integrations overview](/platform/integrations/) - How environments and integrations work together. | |
| * [Slack](/platform/integrations/slack/) and [Linear](/platform/integrations/linear/) - Other chat- and issue-triggered integrations. | |
| * [Managing cloud agents](/platform/managing-cloud-agents/) - Monitor Jira-triggered runs across your team. | |
| * [Environments](/platform/environments/) - Configure where agents run. |
| ### Requirements | ||
|
|
||
| - **Jira Cloud** - Jira Server and Data Center are not supported. | ||
| - **Warp team and eligible plan** - Your team must be on a **Build, Max, or Business** plan with at least **20 credits** available, or on an **Enterprise** plan with a team credit pool. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details. |
There was a problem hiding this comment.
❓ [QUESTION] I couldn't confirm this in warp-server (integration billing policy isn't in the code I reviewed). Two things to verify: (1) the 20-credit minimum, and (2) Enterprise plan with a team credit pool — the Slack and Linear pages list only Build, Max, or Business and don't mention Enterprise. Is Enterprise eligibility Jira-specific/new, or should this match the sibling wording (and should Slack/Linear be updated too)? 👀 @hongyi-chen
There was a problem hiding this comment.
nothing new with jira, we want to match slack and linear as much as we can here. updated!
|
|
||
| ### How to start a run | ||
|
|
||
| Add the label **`oz-agent`** to any Jira issue. Oz will pick it up, post a comment to let you know it's started, and begin working through the task using the issue title, description, and recent comments as context. |
There was a problem hiding this comment.
❓ [QUESTION] How is the triggering user resolved when someone adds the label? The simple_integrations framework maps external users to Warp accounts by email and runs as that user (or a pinned executor / team service account for app-created events). The Jira webhook handler isn't in warp-server yet, so please confirm the Jira label event carries the label-adder's email — this determines whose GitHub identity opens the PR, and the exact wording of the identity requirement suggested in Requirements.
|
|
||
| --- | ||
|
|
||
| ### How to start a run |
There was a problem hiding this comment.
Because this relocates whole sections it isn't a clean one-click suggestion and would collide with the inline suggestions in this review. I recommend applying the other suggestions first, then reordering. I can push the reorder as a commit if you'd like, just lmk!
rachaelrenk
left a comment
rachaelrenk
left a comment
There was a problem hiding this comment.
Left some suggested edits with context + question re: credits in a comment + a note about reordering the sections in this doc. Once those items are addressed/ feedback is implemented, this will be ready to ship 🚀
…n order, troubleshooting - Remove early-access caution block - Add 'using the oz-agent label' to description - Reorder sections: Requirements → Setup → How to start a run → Troubleshooting - Requirements: match Slack/Linear wording exactly (team membership, plan/credits, infrastructure); drop cloud environment, GitHub auth, identity bullets - Step 2: rename to 'Connect your Jira site to Warp' - Step 3: link to oz.warp.dev/integrations (Oz web app) - How to start a run: add Agent Management Panel cross-link - Troubleshooting: switch to * bullets, add error-code tip block, fix community link to Warp Slack - Add Related pages section - index.mdx: add Jira to intro sentence Co-Authored-By: Oz <oz-agent@warp.dev>
rachaelrenk
left a comment
rachaelrenk
left a comment
There was a problem hiding this comment.
Beautiful, thank you! 🛸
2 participants
Summary
Adds an initial docs page for the Jira integration, which lets teams trigger Oz cloud agents from Jira Cloud issues by adding the
oz-agentlabel.Changes
src/content/docs/platform/integrations/jira.mdx— overview, how to start a run, setup, requirements, and troubleshooting.src/sidebar.ts— adds Jira to the Integrations list (after Linear).src/content/docs/platform/integrations/index.mdx— adds a Jira bullet to the "Get started" list.Note on file location
The original task specified the path
src/content/docs/agent-platform/cloud-agents/integrations/jira.mdx. That path is stale —mainhas been restructured so integrations now live undersrc/content/docs/platform/integrations/(seeslack.mdx,linear.mdx, etc.), and the sidebar referencesplatform/integrations/*slugs. The page was placed there instead so it matches the current structure, appears in the sidebar, and isn't orphaned. Page content is unchanged from the spec.Validation
npm run buildsucceeds (341 pages built), including the new Jira page.Artifacts
Co-Authored-By: Oz oz-agent@warp.dev