Skip to content

docs: publish Jira integration page with self-serve setup flow #338

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jasonkeung wants to merge 2 commits into
base: main
Choose a base branch
from
+42 −15
Open

docs: publish Jira integration page with self-serve setup flow #338

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
568f227
docs: publish Jira integration page with self-serve setup flow
jasonkeung Jul 17, 2026
764bc5d
docs: rename Jira URL placeholder to your-site-subdomain
jasonkeung Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/content/docs/platform/integrations/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: >-
---
import VideoEmbed from '@components/VideoEmbed.astro';

Warp integrations let your team trigger agents directly from the terminal, or from tools like [Slack](/platform/integrations/slack/) and [Linear](/platform/integrations/linear/). Once set up, agents can:
Warp integrations let your team trigger agents directly from the terminal, or from tools like [Slack](/platform/integrations/slack/), [Linear](/platform/integrations/linear/), and [Jira](/platform/integrations/jira/). Once set up, agents can:

* Read conversation or issue context
* Run code inside your codebase in a remote environment
Expand All @@ -31,7 +31,7 @@ Use the setup walkthrough below for a quick look at how environments connect to

* [Integrations quickstart](/platform/integrations/quickstart/) - Trigger your first agent from Slack and watch the run from start to finish.
* [Integration setup](/reference/cli/integration-setup/) - Configure environments, GitHub authorization, CLI flags, and integrations in more detail.
* [Slack](/platform/integrations/slack/) and [Linear](/platform/integrations/linear/) - Trigger agents from team conversations, issues, and comments.
* [Slack](/platform/integrations/slack/), [Linear](/platform/integrations/linear/), and [Jira](/platform/integrations/jira/) - Trigger agents from team conversations, issues, and comments.
* [GitHub Actions](/platform/integrations/github-actions/) - Run agents from CI workflows and repository events.
* [GitLab](/platform/integrations/gitlab/), [Bitbucket](/platform/integrations/bitbucket/), and [Azure DevOps](/platform/integrations/azure-devops/) - Connect non-GitHub repositories with tokens and Warp-managed secrets.
* [AWS, GCP, and other cloud providers](/platform/integrations/cloud-providers/) - Give cloud agents short-lived access to cloud services.
Expand Down
52 changes: 39 additions & 13 deletions src/content/docs/platform/integrations/jira.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
---
title: Jira integration
draft: true
sidebar:
label: "Jira"
description: >-
Expand All @@ -23,19 +22,35 @@ The Jira integration lets your team kick off cloud agent runs directly from Jira

### Setup

#### 1. Install the Oz app in Jira
#### 1. Open the Jira app installation page

The Oz app is not yet published to the Atlassian marketplace. Install the Oz app into your Jira Cloud site using the link provided by your Warp contact. Only Jira site admins can install apps.
In the [Oz web app](https://oz.warp.dev/integrations), find Jira and click **Set up**. On the Atlassian installation page, click **Get app**.

#### 2. Connect your Jira site to Warp
#### 2. Install Oz on your Jira site

After installing the app, open the app's **Configure** screen inside Jira. This takes you to a Warp page to connect your app installation to your Warp workspace.
Choose the Jira Cloud site you want to connect, review the requested permissions, and install Oz. Only Jira site admins can install apps.

@hongyi-chen hongyi-chen Jul 17, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

might be worth linking them out to the jira platform somewhere here, just for ease of access

@hongyi-chen hongyi-chen Jul 17, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also, i think worth mentioning a bit about how this affects your jira team - once you install this on jira, does everyone immediately have access to it? does everyone else have to auth into warp / oz?


Once connected, the integration is active for all members of your Warp team.
#### 3. Open the Oz configuration page

#### 3. (Optional) Configure the default environment, model, and harness
In your Jira site, open **Manage apps**. Find Oz, open its three-dot actions menu, then click **Configure**.

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.
The configuration page URL for the production app follows this pattern:

```text
https://<your-site-subdomain>.atlassian.net/jira/settings/apps/configure/40dbc167-16d9-4b68-9752-277c5a52aa01/34808a52-a321-44c2-bac4-a15eb316df50/static/warp-jira-configure/34808a52-a321-44c2-bac4-a15eb316df50
```

Replace `<your-site-subdomain>` with your Jira Cloud site subdomain.

#### 4. Connect Jira to your Warp workspace

On the Oz configuration page in Jira, click **Connect to Warp**. Sign in to Warp if prompted. Warp automatically binds the Jira installation to your Warp workspace.

The confirmation page displays **Jira connected** when the connection succeeds. Jira-triggered runs are now available to members of the connected Warp workspace.

@hongyi-chen hongyi-chen Jul 17, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could be helpful to include a screenshot here!

#### 5. (Optional) Configure the default environment, model, and harness

Return to the [Integrations page in the Oz web app](https://oz.warp.dev/integrations), then click **Edit Jira** to set the default [environment](/platform/environments/), model, harness, and agent for Jira-triggered runs. If you don't change these settings, Oz uses your workspace's default configuration.

---

Expand All @@ -45,6 +60,20 @@ Add the label **`oz-agent`** to any Jira issue. Oz will pick it up, post a comme

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.

#### Connecting your Jira account to Warp

@hongyi-chen hongyi-chen Jul 17, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is there anything an admin needs to do on the jira side? can anyone install warp / oz onto jira, without admin permissions?


The first time you trigger a run, Oz posts a comment prompting you to connect your Jira account to Warp. Connecting attributes your Jira-triggered runs to your Warp account; the run starts either way.

1. Follow the link in the comment to open the Warp page in your Jira personal settings. The link for the production app follows this pattern:

```text
https://<your-site-subdomain>.atlassian.net/jira/settings/personal/apps/40dbc167-16d9-4b68-9752-277c5a52aa01/34808a52-a321-44c2-bac4-a15eb316df50
```

2. Click **Connect to Warp**. A Warp page opens and links your account automatically. Sign in to Warp first if prompted.

The page displays **Jira account connected** when the link succeeds, and the settings page shows a **Connected to Warp** badge. Runs you trigger from then on are attributed to you.

---

### Troubleshooting
Expand All @@ -54,11 +83,8 @@ 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.
* [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/) - the integration was removed or disabled.
:::note
When a Jira-triggered run fails to start, Oz updates its comment on the issue to say it could not start the task. Re-add the `oz-agent` label to try again; a new attempt starts a new comment thread.
:::

For other issues, reach out to your Warp contact or join the [Warp community on Slack](https://go.warp.dev/join-preview).
Expand Down
1 change: 1 addition & 0 deletions src/sidebar.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -363,6 +363,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [
{ slug: 'platform/integrations/quickstart', label: 'Quickstart' },
'platform/integrations/slack',
'platform/integrations/linear',
'platform/integrations/jira',
{
label: 'GitHub Actions',
collapsed: true,
Expand Down
Loading