ROX-33193: Jira Cloud support

[janisz]

Overview

This PR updates junit2jira to work with Jira Cloud by migrating from the deprecated Jira API v2 to v3, switching from andygrunwald/go-jira to ctreminiom/go-atlassian/v2, and converting all templates from Wiki Markup to Atlassian Document Format (ADF).

Problems Encountered and Solutions

1. Authentication Failure (403 Forbidden)

Problem: Initial implementation used PAT (Personal Access Token) authentication with jira.PATAuthTransport, which failed with:

403 Forbidden: "Failed to parse Connect Session Auth Token"

Root Cause: Jira Cloud does not support PAT authentication in the same way as Jira Server/Data Center. Jira Cloud requires Basic Auth using email + API token.

Solution: Changed authentication to Basic Auth:

jiraClient.Auth.SetBasicAuth(jiraUser, jiraToken)
// where jiraUser is email (tjanisze@redhat.com) and jiraToken is the API token

2. API v2 Endpoint Deprecation (410 Gone)

Problem: After fixing authentication, all search requests failed with:

410 Gone: "Migrate to /rest/api/3/search/jql"

Root Cause: Jira Cloud deprecated the /rest/api/2/search endpoint. The error message explicitly instructed migration to /rest/api/3/search/jql.

Investigation: Searched the andygrunwald/go-jira repository and found:

• Issue #345 - tracking the exact same problem
• PR #356 - proposed fix

Solution: Migrated from andygrunwald/go-jira to ctreminiom/go-atlassian/v2 v2.3.0, which has native support for Jira API v3 and the new SearchJQL endpoint.

3. Library Migration Challenges

Problem: The go-atlassian library has a completely different API structure compared to go-jira.

Changes Required:

• Updated imports: github.com/ctreminiom/go-atlassian/v2/jira/v3
• Replaced Issue.Search.Post() with Issue.Search.SearchJQL()
• Changed from pagination with startAt to nextPageToken
• Added context.TODO() to all API calls
• Updated type definitions from jira.Issue to models.IssueScheme

4. Search Results with Nil Fields

Problem: After migration, search returned issues but all had <nil fields>:

Search returned 7 issues (total: 0)
Found issue: ROX-32488 - <nil fields>

Root Cause: The v3 API requires explicitly requesting which fields to return. Passing nil for the fields parameter returns minimal data without the fields we need for matching.

Solution: Changed the SearchJQL call to explicitly request the summary field:

searchResult, response, err := j.jiraClient.Issue.Search.SearchJQL(
    context.TODO(),
    jql,
    []string{"summary"}, // Explicitly request summary field
    nil,
    50,
    "",
)

5. Wiki Markup No Longer Supported

Problem: After successful migration to v3 API, the tool worked for creating issues and comments, but formatting was wrong. Jira Cloud no longer renders Wiki Markup formatting (the original template format used code blocks with {code:title=Message|borderStyle=solid}).

Solution: Converted all templates from Wiki Markup to Atlassian Document Format (ADF), which is the required format for Jira Cloud.

6. ADF Comment Creation Failure (INVALID_INPUT)

Problem: After implementing ADF structure, issue creation worked perfectly but comment creation failed with:

{
  "errorMessages": ["INVALID_INPUT"],
  "errors": {"comment": "INVALID_INPUT"}
}

Investigation:

• Created test comments manually via curl - both simple and table comments worked
• Added debug logging to inspect the JSON payload being sent
• Discovered the issue: empty table cells had text nodes without the text field

Root Cause: When BUILD TAG or ORCHESTRATOR fields were empty strings, the code created text nodes like:

&models.CommentNodeScheme{
    Type: "text",
    Text: "", // Empty string
}

The Go JSON marshaler was serializing this as {"type":"text"} (omitting the empty text field entirely), which violated ADF schema requirements. ADF text nodes must have a text field, even if it's an empty string.

Solution: Added explicit checks to replace empty strings with a space character:

buildTagText := tc.BuildTag
if buildTagText == "" {
    buildTagText = " " // Use space for empty values
}

This ensures the JSON always includes the text field: {"type":"text","text":" "}

Testing

Created Issues (Examples)

• ROX-32502 - Issue created with ADF format, includes table with links
  • Comment 15953312 - Successfully added with fixed empty field handling

Environment Variables

The tool now requires two environment variables for Jira Cloud authentication:

export JIRA_USER="your-email@example.com"  # Your Jira Cloud email
export JIRA_TOKEN="your-api-token"          # API token from https://id.atlassian.com/manage-profile/security/api-tokens

Breaking Changes

• Environment Variables: Now requires JIRA_USER (email) in addition to JIRA_TOKEN
• Jira URL Format: Should use base URL (e.g., https://instance.atlassian.net) not UI paths
• API Version: Only works with Jira Cloud API v3 (v2 is deprecated)

References

• Jira Cloud API v3 Documentation
• Atlassian Document Format (ADF) Specification
• go-atlassian v2 Documentation
• Issue #345 - go-jira - v2 API deprecation
• PR #356 - go-jira - Proposed fix for v3