JIRA Integration Setup

This guide will help you set up JIRA integration with Codity to automatically link JIRA tickets to pull request reviews and verify that PRs meet ticket requirements.

Overview

The JIRA integration allows Codity to:

  • Extract JIRA ticket IDs from PR titles and descriptions
  • Fetch ticket details and requirements from JIRA
  • Verify that PRs meet the acceptance criteria defined in JIRA tickets
  • Include JIRA context in PR review feedback

Prerequisites

  • A JIRA account (JIRA Cloud or self-hosted instance)
  • Admin access to create API tokens in JIRA
  • Access to the JIRA projects you want to integrate
  • A Codity account with at least one connected provider (GitHub, GitLab, Azure DevOps, or Bitbucket)

Setup Steps

Step 1: Create a JIRA API Token

  1. Navigate to JIRA Account Settings
    • Go to https://id.atlassian.com/manage-profile/security/api-tokens
    • Or go to JIRA → Account Settings → Security → API tokens
  2. Create API Token
    • Click "Create API token"
    • Enter a label: Codity Integration (or any descriptive name)
    • Click "Create"
    • IMPORTANT: Copy the token immediately - you won't be able to see it again
    • Store it securely

Step 2: Configure JIRA in Codity Dashboard

  1. Navigate to Settings
    • Log in to your Codity dashboard
    • Go to Settings → Integrations (or Settings → JIRA)
  2. Enter JIRA Configuration
    • JIRA URL: Enter your JIRA instance URL
      • For JIRA Cloud: https://your-workspace.atlassian.net
      • For self-hosted: https://jira.yourcompany.com
    • Email: Enter the email address associated with your JIRA account
    • API Token: Paste the API token you created in Step 1
    • Project Keys: Enter comma-separated project keys (e.g., PROJ,DEV,TEST)
      • These are the JIRA project keys you want Codity to recognize
      • Example: If your tickets are PROJ-123, DEV-456, enter PROJ,DEV
      • Leave empty to recognize all project keys
  3. Test Connection
    • Click "Test Connection" to verify your credentials
    • You should see a success message with your JIRA display name
    • If the test fails, check your URL, email, and API token
  4. Save Settings
    • Click "Save" to store your JIRA configuration
    • Settings are encrypted and stored securely

JIRA integration automatically extracts ticket IDs from PR titles and descriptions. Supported formats:

  • PROJ-123 - Standard format
  • [PROJ-123] - Bracketed format
  • (PROJ-123) - Parenthesized format
  • PROJ-123, PROJ-124 - Multiple tickets

Example PR Titles:

  • Fix login bug PROJ-123
  • [PROJ-123] Implement user authentication
  • Add feature (PROJ-123, PROJ-124)

Step 4: Verify Integration

  1. Create a Test PR
    • Create a pull request with a JIRA ticket ID in the title or description
    • Example: Fix issue PROJ-123
  2. Wait for Review
    • Codity will automatically detect the JIRA ticket
    • Fetch ticket details and requirements
    • Include JIRA context in the PR review
  3. Check Review Comments
    • Look for JIRA context section in the review comments
    • Verify that acceptance criteria from JIRA are included
    • Confirm that PR requirements match JIRA ticket requirements

How It Works

Ticket Detection

Codity automatically scans PR titles and descriptions for JIRA ticket IDs using pattern matching:

  • Recognizes standard JIRA ticket formats (e.g., PROJ-123)
  • Supports multiple tickets in a single PR
  • Filters by project keys if configured

Ticket Fetching

When a ticket is detected:

  1. Codity fetches ticket details from JIRA API
  2. Extracts ticket summary, description, and acceptance criteria
  3. Classifies ticket type (Bug, Story, Task, etc.)
  4. Identifies requirement fields (Acceptance Criteria, Description, etc.)

Requirement Verification

Codity uses JIRA ticket information to:

  • Verify PR changes align with ticket requirements
  • Check that acceptance criteria are met
  • Provide context-aware review feedback
  • Link PR comments back to JIRA tickets

Best Practices

  1. Use Project Keys: Configure project keys to limit ticket recognition to relevant projects
  2. Keep API Tokens Secure: Never share API tokens or commit them to version control
  3. Rotate Tokens Periodically: Update API tokens every 90 days for security
  4. Test After Changes: After updating JIRA settings, create a test PR to verify integration
  5. Use Descriptive Ticket IDs: Include JIRA ticket IDs in PR titles for better visibility
  6. Maintain Ticket Quality: Ensure JIRA tickets have clear acceptance criteria for better PR reviews
  7. Monitor Integration: Periodically check that JIRA tickets are being detected and fetched correctly

API Token Management

Creating New Tokens

  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click "Create API token"
  3. Enter label and create
  4. Copy token immediately
  5. Update in Codity dashboard

Revoking Tokens

  1. Go to API tokens page
  2. Find the token you want to revoke
  3. Click "Revoke"
  4. Update Codity with a new token

Token Expiration

  • API tokens don't expire by default
  • You can revoke them at any time
  • Best practice: Rotate tokens every 90 days

Security Considerations

  1. Token Storage: JIRA API tokens are encrypted using Fernet encryption before storage
  2. Access Control: Only authorized users can view/update JIRA settings
  3. API Communication: All communication with JIRA uses HTTPS
  4. Token Scope: API tokens have read-only access to tickets (no write permissions)
  5. Audit Logging: JIRA API calls are logged for debugging (without sensitive data)

Next Steps