Skip to main content
Waterline connects to Jira Cloud with read-only access so it can fetch ticket details and extract acceptance criteria. Once connected, you enter a ticket key and Waterline returns a progress score backed by code evidence. This page covers how to connect, what Waterline reads, and how to set things up if you’re self-hosting.

​
Connect via OAuth

1

Open Jira settings

In Waterline, go to Settings → Integrations → Jira and click Connect Jira.
2

Authorize on Atlassian

You’ll be redirected to Atlassian’s OAuth 2.0 authorization page. Sign in with your Atlassian account and grant access.
3

Select your Jira site

If your Atlassian account has multiple Jira Cloud sites, choose which one Waterline should access.
4

Done

You’ll be redirected back to Waterline. Jira is connected and ready to use.
OAuth scopes Waterline requests:
ScopeWhy Waterline needs it
read:jira-workRead issues, projects, and boards
read:jira-userRead user profiles
read:meIdentify the connected account
offline_accessRefresh tokens silently — so you don’t have to re-authorize repeatedly
Waterline requests no write scopes. It never creates, updates, or deletes Jira issues.

​
What Waterline reads from Jira

When you analyze a ticket, Waterline fetches the following fields:
FieldHow Waterline uses it
SummaryDisplayed in results and used for context
DescriptionParsed to extract acceptance criteria
Acceptance criteria (custom field)Directly extracted if the field exists on the issue
StatusDisplayed alongside the progress score
AssigneeDisplayed alongside the progress score
If your Jira project doesn’t have a dedicated acceptance criteria field, Waterline’s LLM extracts criteria from the description automatically. A structured field helps, but isn’t required.

​
Analyzing a ticket

Once Jira is connected, go to Analyze and enter a Jira ticket key: 
PROJ-123
Waterline will:
  1. Fetch the ticket from Jira
  2. Extract acceptance criteria from the description or custom field
  3. Search your indexed codebase for relevant symbols
  4. Map code evidence to each criterion
  5. Return a progress percentage

​
Troubleshooting

Make sure you’re signing in with an Atlassian account that has access to the Jira site you want to connect. If your organization uses SSO, complete the SSO flow before authorizing Waterline.
Confirm the ticket key is correct (PROJ-123, not proj-123 or PROJ 123). Also check that the Jira site you connected is the one that contains the project.
Waterline automatically rotates refresh tokens. If the token is revoked — for example, if you removed the app in Atlassian’s security settings — go to Settings → Integrations → Jira and reconnect.
Waterline currently supports Jira Cloud only. Jira Data Center and Jira Server use different API endpoints and auth flows that are not yet supported.

​
Self-hosted OAuth app setup

If you’re running Waterline yourself, create a Jira OAuth 2.0 app at developer.atlassian.com:
1

Create the app

Click Create → OAuth 2.0 integration and give it a name.
2

Add a callback URL

Under Authorization, add the callback URL:
https://your-api.com/api/connect/jira/callback
3

Add scopes

Add the four scopes listed above: read:jira-work, read:jira-user, read:me, and offline_access.
4

Copy credentials

Copy the Client ID and Client Secret from the app settings page.
5

Set environment variables

Add the credentials to your .env:
JIRA_CLIENT_ID=your_client_id
JIRA_CLIENT_SECRET=your_client_secret
JIRA_REDIRECT_URI=https://your-api.com/api/connect/jira/callback