How Atlassian-Rovo Implements JQL-Powered Workflows for Issue Management

The Atlassian-Rovo plugin constructs sanitized JQL queries through reusable builder functions, executes them via the searchJiraIssuesUsingJql tool, and processes results to automate triage, status reporting, and Confluence publishing without manual Jira navigation.

The Atlassian-Rovo plugin demonstrates a production-ready approach to JQL-powered issue management within the OpenAI plugins ecosystem. By separating query construction, execution, and business logic into distinct architectural layers, the plugin transforms natural language requests into precise Jira Query Language commands. This architecture enables automated workflows ranging from duplicate issue detection to executive-level status reports while maintaining strict injection-safety standards.

Three-Layer Architecture for JQL Automation

The plugin organizes its JQL-powered workflows into three distinct architectural layers that handle query construction, data retrieval, and post-processing actions.

JQL Construction Layer

At the foundation lies plugins/atlassian-rovo/skills/generate-status-report/scripts/jql_builder.py, which exposes reusable helper functions for converting high-level parameters into injection-free JQL strings. Functions like build_project_query, build_blocked_query, and build_completed_query accept parameters including project keys, statuses, priorities, date ranges, and assignee values.

Each function sanitizes inputs through sanitize_jql_value, which whitelists characters and escapes double quotes to prevent JQL injection attacks. The builder constructs clause lists that are joined with AND operators and appended with optional ORDER BY clauses for consistent result ordering.

Search and Retrieval Layer

The constructed JQL strings feed into the searchJiraIssuesUsingJql tool exposed by the OpenAI plugins runtime, as declared in plugins/atlassian-rovo/.codex-plugin/plugin.json. According to the skill definitions in plugins/atlassian-rovo/skills/triage-issue/SKILL.md and plugins/atlassian-rovo/skills/generate-status-report/SKILL.md, this tool accepts cloudId, jql, fields, and maxResults parameters.

The implementation handles pagination through nextPageToken values, allowing the plugin to retrieve large issue sets beyond single-request limits. Standard field requests include summary, status, priority, assignee, created, and updated to provide comprehensive issue context.

Analysis and Action Layer

Once retrieved, issues undergo domain-specific processing defined in SKILL markdown files. The triage-issue workflow calculates duplicate confidence scores by comparing error signatures and component mappings, then branches between adding comments to existing issues via addCommentToJiraIssue or creating new tickets via createJiraIssue.

The generate-status-report workflow aggregates metrics by status and priority, selects appropriate templates (executive, team-level, or daily), and optionally publishes formatted Markdown to Confluence using createConfluencePage. This layer transforms raw JQL results into actionable intelligence and automated documentation.

Implementing Safe JQL Construction

Safety and modularity drive the query building implementation. The jql_builder.py module centralizes all query generation, ensuring consistent sanitization across multiple skills including triage, status reports, and spec-to-backlog workflows.

The sanitize_jql_value function serves as the primary defense against injection, processing user-supplied strings before they enter clause construction. New query patterns can be added by extending the builder module or referencing plugins/atlassian-rovo/skills/generate-status-report/references/jql-patterns.md, which documents common JQL formulations used throughout the plugin.

Practical Implementation Examples

Constructing Project-Wide Queries

To fetch open high-priority issues from the past week, developers use the builder pattern:

from plugins.atlassian_rovo.skills.generate_status_report.scripts.jql_builder import build_project_query

jql = build_project_query(
    project_key="PROJ",
    statuses=["To Do", "In Progress"],
    exclude_done=True,
    priorities=["Highest", "High"],
    days_back=7,
    assignee="EMPTY",
    order_by="priority DESC, updated DESC"
)

This generates the final JQL string:

project = "PROJ" AND status IN ("To Do", "In Progress") AND priority IN ("Highest", "High") AND updated >= -7d AND assignee is EMPTY ORDER BY priority DESC, updated DESC

Executing Searches

The plugin executes queries through the runtime tool:

search_results = searchJiraIssuesUsingJql(
    cloudId="my-cloud-id",
    jql=jql,
    fields=["summary", "status", "priority", "assignee", "created", "updated"],
    maxResults=50
)

Automating Triage Actions

When duplicate detection triggers, the plugin adds structured comments:

addCommentToJiraIssue(
    cloudId="my-cloud-id",
    issueIdOrKey="PROJ-456",
    commentBody="""

## Additional Instance Reported

**Reporter:** Jane Doe  
**Date:** 2026-06-20  

**Error Details:** Connection timeout during login

*Added via Atlassian-Rovo triage automation*
"""
)

Publishing Status Reports

For executive reporting, the plugin creates Confluence pages:

createConfluencePage(
    cloudId="my-cloud-id",
    spaceId="12345",
    title="Project PROJ - Weekly Status - 2026-06-20",
    body=formatted_markdown_report,
    contentFormat="markdown"
)

Summary

• Modular JQL Construction: The jql_builder.py module provides reusable, injection-safe query generation through functions like build_project_query and sanitize_jql_value.
• Runtime Integration: Skills invoke searchJiraIssuesUsingJql with constructed queries, handling pagination via nextPageToken and requesting standard fields including summary, status, and priority.
• Automated Action Layer: Retrieved data drives business logic for duplicate detection, metric aggregation, and automated publishing to Jira and Confluence.
• Security-First Design: Input sanitization and declarative workflow definitions in SKILL markdown files ensure safe, maintainable automation.

Frequently Asked Questions

How does Atlassian-Rovo prevent JQL injection vulnerabilities?

The plugin passes all user-supplied strings through sanitize_jql_value before incorporating them into queries. This function whitelists safe characters and escapes double quotes, ensuring that malicious input cannot break out of JQL string literals or alter query logic. The centralized sanitization in jql_builder.py guarantees consistent security across all skills.

What determines whether the triage workflow comments on an existing issue or creates a new one?

The triage skill calculates duplicate confidence scores by comparing error signatures, components, and symptoms from the user's request against existing issues retrieved via JQL. If confidence exceeds defined thresholds, the workflow selects addCommentToJiraIssue (Option A). Otherwise, it executes createJiraIssue (Option B) to generate a new ticket.

Can the plugin handle complex JQL patterns beyond simple equality checks?

Yes. The jql_builder.py module supports complex patterns including IN clauses for multiple statuses or priorities, date range queries using relative time syntax like -7d, and ORDER BY clauses with multiple sort fields. The references/jql-patterns.md file documents additional patterns for cross-project queries, blocked issue identification, and completed issue retrieval.

Which specific Jira fields does the plugin request during search operations?

According to the SKILL definitions, the plugin typically requests summary, status, priority, assignee, created, and updated fields. These provide sufficient context for triage decisions and status report generation while minimizing payload size. The fields parameter in searchJiraIssuesUsingJql accepts custom field identifiers when additional data is required for specific workflows.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}