Validate Bug

JIRA Bug Validator — Implementation Guide

IMPORTANT FOR AI: This is a procedural skill. Execute each phase in order. Do not skip steps. Do not invent field IDs — use only the documented custom field IDs below.

This skill replicates the validation logic of the jira-lifecycle-plugin (Prow external plugin) that applies the jira/invalid-bug label to PRs in OpenShift repositories.

Custom Field Reference

The 7 Validation Checks

The jira-lifecycle-plugin runs these checks in order. A bug must pass ALL checks to get jira/valid-bug.

Checks 5-7 only apply to release branches (release-4.X), not main/master.

Branch-to-Version Mapping

The plugin config follows a mechanical pattern:

Target version (what the bug on the PR's branch must target):

• release-4.X → 4.X.z (prefix match — 4.X.0 also accepted)
• main / master → 5.0.0 (prefix match — 5.0 also accepted). Update when main targets a new major version — check openshift/release/core-services/jira-lifecycle-plugin/config.yaml for the current value.

Dependent target version (what the "Blocks" linked bug must target):

• release-4.X → 4.(X+1).0 or 4.(X+1).z

Valid states for the bug itself (all branches):

• NEW, ASSIGNED, POST

Valid states for dependent bugs (varies by branch — check openshift/release/core-services/jira-lifecycle-plugin/config.yaml for current boundaries):

• release-4.22 and newer: MODIFIED, ON_QA, VERIFIED
• release-4.6 through release-4.21: VERIFIED, RELEASE PENDING, CLOSED (ERRATA), CLOSED (CURRENT RELEASE), CLOSED (DONE), CLOSED (DONE-ERRATA)

Dependent bug checks (checks 5-7):

• Required for release-4.X branches
• NOT required for main / master (config sets exclude_defaults: true)

Release notes:

• Required by default (require_release_notes: true)
• Default template text (must NOT match this): "Cause: What actions or circumstances cause this bug to present.\r\nConsequence: What happens when the bug presents.\r\nFix: What was done to fix the bug.\r\nResult: Bug doesn't present anymore."

Prerequisites

• gh CLI authenticated with GitHub
• Jira MCP server configured (Atlassian Rovo MCP)
• cloudId: use redhat.atlassian.net

Detailed Implementation Steps

Phase 1: Resolve Input

Parse the argument to determine input type:

1. PR URL — matches https://github.com/{org}/{repo}/pull/{number}

   • Extract org, repo, and PR number from the URL
   • Run: gh pr view {number} --repo {org}/{repo} --json title,baseRefName,state
   • Extract JIRA key from PR title using regex: first match of [A-Z]+-[0-9]+ (e.g., OCPBUGS-85778)
   • Extract base branch from baseRefName (e.g., release-4.20, main)

2. PR number — plain integer

   • Determine repo from current git remote: gh repo view --json nameWithOwner -q .nameWithOwner
   • Then same as PR URL flow above

3. JIRA key — matches [A-Z]+-[0-9]+

   • Require --branch argument (no PR context to infer branch)
   • If --branch not provided, error: "JIRA key input requires --branch (e.g., --branch release-4.20)"

Validate the JIRA key project:

• Must be a bug project: OCPBUGS, DFBUGS, or PROJQUAY
• If not, warn: "Project {PROJECT} is not a bug project. The jira-lifecycle-plugin only validates bugs in OCPBUGS, DFBUGS, and PROJQUAY."

Compute expected values from branch:

• Parse branch name to extract version number
• Compute expected_target_version, expected_dependent_versions, valid_states, dependent_valid_states, dependents_required using the mapping above

Phase 2: Gather Data

Fetch the primary bug:

Use mcp__atlassian__getJiraIssue:

• cloudId: redhat.atlassian.net
• issueIdOrKey: the JIRA key
• fields: ["summary", "status", "issuetype", "fixVersions", "issuelinks", "customfield_10855", "customfield_10783", "customfield_10785", "customfield_10840", "labels", "components"]
• responseContentFormat: markdown

Extract key data from response:

• status.name — bug status (e.g., "New", "Verified")
• customfield_10855 — Target Version array (each entry has .name)
• customfield_10783 — Release Note Text (string or ADF doc)
• customfield_10785 — Release Note Type (object with .value)
• issuelinks — array of issue links

Find dependent bugs:

Filter issuelinks for links where:

• Link type name is "Blocks" AND direction is outwardIssue (this bug blocks the dependent)
• The linked issue's project key matches the original bug's project (e.g., both are OCPBUGS-*)

For each dependent found:

• Record the dependent's key, status, and priority from the link data
• If the link data doesn't include Target Version, fetch the dependent with getJiraIssue:
  • fields: ["summary", "status", "customfield_10855", "fixVersions"]

Phase 3: Validate

Run each check and record the result:

results = []

Check 1: Bug is open

• PASS if status.name is NOT "Closed"
• FAIL if status.name is "Closed"
• Pass message: "bug is open, matching expected state (open)"
• Fail message: "bug is closed, expected it to be open"

Check 2: Target version matches branch

• Get target versions from customfield_10855 (array)
• FAIL if no target version is set: "expected the bug to target the '{expected}' version, but no target version was set"
• FAIL if multiple target versions are set (only one allowed)
• PASS if exactly one target version and its .name starts with the expected prefix (e.g., "4.20" for release-4.20)
• FAIL otherwise: "expected the bug to target either version '{expected}' or 'openshift-{expected}', but it targets '{actual}' instead"

Check 3: Bug in valid state

• PASS if status.name (uppercased) is in ["NEW", "ASSIGNED", "POST"]
• FAIL otherwise: "bug is in state {actual}, which is not one of the valid states (NEW, ASSIGNED, POST)"

Check 4: Release notes

• Get release note text from customfield_10783
  • If it's an ADF document, extract the plain text content
  • If it's a string, use directly
• Get release note type from customfield_10785
• PASS if release note type .value equals "Release Note Not Required"
• PASS if release note text is non-empty AND does NOT start with "Cause: What actions or circumstances"
• FAIL otherwise: "release note text must be set and not match the template OR release note type must be set to 'Release Note Not Required'"

Check 5: Dependent bug states (skip if dependents_required is false)

• For each dependent bug found via "Blocks" links:
  • PASS if dependent's status.name (uppercased) is in the allowed dependent_valid_states list
  • FAIL otherwise: "expected dependent Jira Issue {key} to be in one of the following states: {allowed}, but it is {actual} instead"
• If no dependents exist, this check is implicitly skipped (check 7 handles that)

Check 6: Dependent bug target versions (skip if dependents_required is false)

• For each dependent bug:
  • Get its Target Version from customfield_10855
  • PASS if target version starts with one of the expected_dependent_versions prefixes
  • FAIL otherwise: "expected dependent Jira Issue {key} to target a version in {allowed}, but it targets '{actual}' instead"

Check 7: Dependents exist (skip if dependents_required is false)

• PASS if at least one "Blocks" link exists to a bug in the same project
• FAIL otherwise: "expected Jira Issue to depend on a bug targeting a version in {allowed} and in one of the following states: {allowed_states}, but no dependents were found"