Jira Integration

GuideMode integrates with Jira Cloud to provide visibility into your project management workflow. This integration enables team sync, issue tracking via webhooks, and links Jira work items to your development analytics.

What You Get

• Team Sync: Sync Jira teams or groups to GuideMode for team-based analytics
• Issue Tracking: Real-time updates on issue creation and changes via webhooks
• User Linking: Automatically link Jira users to GuideMode accounts by email
• Work Analytics: Connect Jira issues to your development metrics

Prerequisites

Before setting up the Jira integration, you’ll need:

• A Jira Cloud account (Jira Server/Data Center not currently supported)
• Admin access to create an Atlassian OAuth app
• For team sync: Either Jira admin permissions or an API token

Setup Overview

The Jira integration uses:

1. Atlassian OAuth App - For user authentication and API access
2. Webhooks - For real-time issue updates
3. API Token (optional) - For enhanced team sync capabilities

Step 1: Create an Atlassian OAuth App

1. Go to Atlassian Developer Console
2. Click Create > OAuth 2.0 integration
3. Fill in the details:
   • Name: GuideMode (or your preferred name)
   • Description: Integration with GuideMode analytics

Configure Authorization

4. In your app settings, go to Authorization > Add
5. Select OAuth 2.0 (3LO)
6. Add callback URL: https://guidemode.dev/auth/jira/callback
7. Save changes

Set Permissions (Scopes)

8. Go to Permissions > Add
9. Add the Jira API product
10. Configure these scopes:

Required scopes:

• read:me - Access user identity
• offline_access - Refresh token support

Admin scopes (for webhooks and team sync):

• read:jira-work - Read Jira issues
• read:jira-user - Read user profiles
• read:email-address:jira - Fetch user emails
• read:group:jira - Read user groups
• manage:jira-configuration - Admin access
• manage:jira-webhook - Create/manage webhooks

Get Credentials

11. Go to Settings
12. Copy the Client ID and Secret

Step 2: Environment Configuration

Add these environment variables to your GuideMode deployment:

JIRA_CLIENT_ID=your_oauth_client_id
JIRA_SECRET=your_oauth_secret
JIRA_REDIRECT_URI=https://guidemode.dev/auth/jira/callback

For local development, add these to your .dev.vars file in the server app.

Step 3: Connect Your Account

Basic Login

1. Navigate to Settings > Jira in GuideMode
2. Click Connect with Jira
3. Authorize the application
4. Select which Jira sites to grant access to

Admin Authorization

To use webhooks and team sync, you need admin-level permissions:

1. Go to Settings > Jira
2. Click Re-authenticate with Admin Permissions
3. Approve the additional scopes
4. Your account now has admin capabilities

Team Sync

GuideMode can sync your Jira teams to enable team-based analytics.

Two Sync Methods

GuideMode supports two methods for team sync:

Method	Requires	What’s Synced	Best For
Team API	API Token	Actual Jira teams	Organizations with formal teams
Groups API	OAuth only	Jira groups	Quick setup without API token

Method 1: Team API (Recommended)

The Team API syncs actual Jira teams with full membership data.

Setup:

1. Create an API token at Atlassian Account Settings
2. Go to Settings > Jira in GuideMode
3. Enter your:
   • Email address: The email associated with your Atlassian account
   • API Token: The token you generated
   • Organization ID: Found in your Jira admin settings
4. Click Save API Token

Triggering a Sync:

1. Click Sync Teams
2. Wait for the sync to complete
3. Review synced teams in Team settings

Method 2: Groups API (Fallback)

If you don’t want to set up an API token, GuideMode can sync Jira groups instead.

Note: Jira groups are not the same as teams. Groups are typically used for permissions, while teams are project-based. For best results, use the Team API.

How it works:

• Uses your OAuth token (no API token needed)
• Syncs all groups you have access to
• Creates teams in GuideMode for each group
• Links members by email

What Gets Synced

Data	Description
Teams/Groups	Name, description, membership
Members	User profiles, email addresses
Roles	Member roles within teams

User Linking

When syncing, GuideMode links Jira users to existing accounts:

1. By Jira Account ID: If user was previously synced
2. By Email: If emails match between systems
3. New User: Created if no match found (requires email access)

Users with private email settings may not be linkable.

Webhook Configuration

Webhooks provide real-time updates when issues change in Jira.

Prerequisites

• Admin-level OAuth permissions
• Webhook URL must be accessible from Jira

Creating a Webhook

1. Go to Settings > Jira
2. Select the Jira site to configure
3. Click Create Webhook
4. Configure options:
   • Events: Issue created, Issue updated, Issue deleted
   • JQL Filter (optional): Filter which issues trigger webhooks

Webhook Events

Event	When Triggered
jira:issue_created	New issue is created
jira:issue_updated	Issue fields are modified
jira:issue_deleted	Issue is deleted

Webhook Expiration

Jira webhooks expire after 30 days. GuideMode will:

• Notify you before expiration
• Allow you to extend the webhook
• Automatically prompt for refresh

To extend a webhook:

1. Go to Settings > Jira
2. Find the webhook in the list
3. Click Refresh to extend by 30 days

JQL Filtering

You can filter which issues trigger webhooks using JQL:

project = "MYPROJECT" AND issuetype != "Sub-task"

This reduces webhook volume and focuses on relevant issues.

Issue Type Mapping

GuideMode maps Jira issue types to internal categories for consistent analytics across projects.

Issue Categories

Type	Typical Jira Types	Description
feature	Story, New Feature, Epic	New functionality
bug	Bug, Defect	Issues and fixes
chore	Task, Technical Task	Maintenance work
discovery	Spike, Research	Investigation work
incident	Incident, Production Issue	Urgent fixes
other	Unmatched types	Default category

Default Mapping

GuideMode uses heuristics based on issue type names (case-insensitive, partial matching):

Bug: Types containing bug, defect, fix

Feature: Types containing story, feature, epic, enhancement

Chore: Types containing task, chore, maintenance, technical

Discovery: Types containing spike, research, investigation, discovery

Incident: Types containing incident, outage, emergency

Custom Mappings

You can configure custom type mappings per project. Custom mappings take priority over defaults.

Issue State Tracking

Jira provides richer state information than GitHub:

Jira Status Category	GuideMode State	Description
To Do	open	Not started
In Progress	in_progress	Actively being worked on
Done	closed	Completed

This enables more accurate cycle time and flow metrics compared to GitHub’s simple open/closed states.

Configuration Reference

Environment Variables

Variable	Required	Description
JIRA_CLIENT_ID	Yes	OAuth app Client ID
JIRA_SECRET	Yes	OAuth app Secret
JIRA_REDIRECT_URI	Yes	Callback URL for OAuth

API Token (per user)

Setting	Description
Email	Atlassian account email
API Token	Generated token from Atlassian
Organization ID	Your Jira organization identifier

Webhook Settings

Setting	Description
Site	Which Jira site to receive events from
Events	Which events trigger the webhook
JQL Filter	Optional filter for issue scope
Expiration	30 days from creation/refresh

Troubleshooting

OAuth Login Fails

• Verify JIRA_CLIENT_ID and JIRA_SECRET are correct
• Check the callback URL matches exactly: {APP_URL}/auth/jira/callback
• Ensure all required scopes are configured in the app

Cannot Create Webhooks

• Ensure you have admin-level OAuth permissions
• Re-authenticate with admin scopes if needed
• Verify the webhook URL is publicly accessible

Team Sync Fails

• With API Token: Verify token is valid and not expired
• Without API Token: Check you have read:group:jira scope
• Confirm organization ID is correct
• Check that you have access to the teams/groups

Users Not Linking

• Users must have public email addresses
• Verify emails match between Jira and GuideMode
• Check that read:email-address:jira scope is granted

Webhooks Not Received

• Verify webhook URL is accessible
• Check webhook hasn’t expired (30-day limit)
• Review JQL filter isn’t too restrictive
• Check Jira webhook logs for delivery errors

Stale Webhook Data

• Webhooks only capture changes after creation
• Historical data requires manual import or API sync
• Ensure webhook hasn’t lapsed (30-day expiration)

Limitations

Jira Cloud Only

This integration supports Jira Cloud only. Jira Server and Data Center are not currently supported due to different authentication mechanisms.

Webhook Security

Unlike GitHub, Jira webhooks don’t include HMAC signatures for payload verification. GuideMode validates webhooks by:

• Tenant ID in the URL path
• Cloud ID matching the registered configuration

API Rate Limits

Atlassian enforces API rate limits. Heavy sync operations may be throttled. Team sync is designed to minimize API calls through batching.

Private Profiles

Users with private email settings cannot be automatically linked. They’ll need to manually connect their accounts or make their email visible.