bug-tracker-workflow

Overview

Every mainstream tracker exposes the same four core operations - create, transition, search, and update/comment - behind a different API shape. This skill runs the bug workflow tracker-agnostically, with Jira Cloud REST API v3 worked in full below and per-platform deep dives in references:

Tracker	API shape	Lifecycle model	Deep dive
Jira Cloud	REST v3, ADF rich text	Configurable workflow engine; look up transition IDs at runtime	Worked below + references/jira.md
Linear	GraphQL only	Per-team WorkflowState objects; resolve by type, not display name	references/linear.md
GitHub Issues	REST + Projects v2 GraphQL	Two states (open/closed) + state_reason; severity/priority via labels	references/github-issues.md
Azure DevOps	WIT REST 7.1, JSON Patch	Process-template states (Agile: New/Active/Resolved/Closed); WIQL search	references/azuredevops.md

The tracker-agnostic rules that hold on all four platforms:

• Dedupe before create. CI bug filing must not duplicate when the same failure recurs: search open bugs by title/summary first, comment on the existing bug on a hit, and fail closed (skip the create, surface the error) if the search itself errors.
• Severity and priority are different axes - keep both fields and score them independently (severity-vs-priority-reference).
• Never hard-code lifecycle identifiers. Jira transition IDs, Linear state names, and ADO state strings are all tenant/team/process-specific - discover them at runtime.
• Dry-run bulk operations. Bulk transitions are not trivially reversible; log the plan and verify counts before applying.
• Secrets in env vars / secret stores, never in code.

When to use

• Filing a bug from a CI test failure (fed by the from-CI-failure workflow in bug-report-template, qa-bug-repro).
• Bulk-transitioning bugs after a release.
• Building a triage script that pulls new defects and applies severity / priority based on labels.
• Backing a duplicate-defect search backend.

Worked primary - Jira Cloud REST API v3

Jira's workflow engine maps cleanly to the canonical defect lifecycle (see the lifecycle reference in severity-vs-priority-reference), but every project's actual workflow is configurable, so the runner looks up transition IDs at runtime rather than hard-coding them. All calls per developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/.

Authentication

Jira Cloud REST API v3 uses HTTP Basic auth with an API token:

export JIRA_BASE="https://your-tenant.atlassian.net"
export JIRA_EMAIL="you@company.com"
export JIRA_TOKEN="<api-token-from-id.atlassian.com>"

import requests, base64, os

auth = base64.b64encode(
    f"{os.environ['JIRA_EMAIL']}:{os.environ['JIRA_TOKEN']}".encode()
).decode()
HEADERS = {
    "Authorization": f"Basic {auth}",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
BASE = os.environ["JIRA_BASE"]

Create a bug

POST /rest/api/3/issue. The description must be Atlassian Document Format (ADF), not plain text.

def create_bug(project_key, summary, description_text, severity, priority, labels):
    payload = {
        "fields": {
            "project": {"key": project_key},
            "summary": summary,
            "description": {
                "type": "doc",
                "version": 1,
                "content": [{
                    "type": "paragraph",
                    "content": [{"type": "text", "text": description_text}],
                }],
            },
            "issuetype": {"name": "Bug"},
            "priority": {"name": priority},   # e.g. "High"
            "labels": labels + [f"severity-{severity}"],
        }
    }
    r = requests.post(f"{BASE}/rest/api/3/issue", json=payload, headers=HEADERS)
    r.raise_for_status()
    return r.json()["key"]

Note: severity is typically a custom field - most tenants either define a custom Severity field (customfield_XXXXX) or use labels (severity-critical). The example uses labels for portability; discovering and submitting the custom field is in references/jira.md.

Look up and apply a transition

Workflow transitions are project-specific. Look up the available transitions then apply by transition ID:

def get_transitions(issue_key):
    r = requests.get(f"{BASE}/rest/api/3/issue/{issue_key}/transitions",
                     headers=HEADERS)
    r.raise_for_status()
    return r.json()["transitions"]

def transition(issue_key, target_state_name):
    transitions = get_transitions(issue_key)
    match = next((t for t in transitions if t["name"] == target_state_name), None)
    if not match:
        raise ValueError(f"No transition named {target_state_name}; "
                         f"available: {[t['name'] for t in transitions]}")
    r = requests.post(
        f"{BASE}/rest/api/3/issue/{issue_key}/transitions",
        json={"transition": {"id": match["id"]}},
        headers=HEADERS,
    )
    r.raise_for_status()

The POST /rest/api/3/issue/{key}/transitions body shape is {"transition": {"id": "<id>"}} per the API group docs.

Search via JQL

POST /rest/api/3/search/jql returns issues matching a JQL query. Useful for duplicate detection and triage queues.

def search_jql(jql, max_results=50):
    r = requests.post(
        f"{BASE}/rest/api/3/search/jql",
        json={"jql": jql, "fields": ["summary", "status", "priority"],
              "maxResults": max_results},
        headers=HEADERS,
    )
    r.raise_for_status()
    return r.json()["issues"]

# Triage queue:
triage = search_jql(
    'project = ENG AND issuetype = Bug AND status = "New" ORDER BY created ASC'
)

# Duplicate-candidate search:
dupes = search_jql(
    f'project = ENG AND text ~ "{summary_safe}" AND issuetype = Bug'
)

Idempotent bug creation

def create_or_attach(project, summary, body):
    existing = search_jql(
        f'project = {project} AND summary ~ "\\"{summary}\\"" '
        f'AND statusCategory != Done',
        max_results=5,
    )
    if existing:
        # Attach a comment to the existing bug instead of duplicating
        key = existing[0]["key"]
        add_comment(key, f"Recurred at {timestamp()}: {body[:500]}")
        return key
    return create_bug(project, summary, body, "Medium", "Medium",
                      labels=["auto-filed", "ci-failure"])

Verify: the statusCategory != Done search must run and return 0 open matches before create_bug fires. If it returns a hit, comment on that key instead of creating; if the search itself errors, fail closed (skip the create and surface the error) rather than filing a possible duplicate.

Bulk transition after release

Dry-run first: a mis-scoped JQL can push hundreds of issues into the wrong state, and a transition is not trivially reversible. Gate the apply behind a flag:

DRY_RUN = True  # flip to False only after reviewing the logged plan

verified = search_jql(
    'project = ENG AND status = Verified AND fixVersion = "2026.05.20"',
    max_results=1000,
)
for issue in verified:
    if DRY_RUN:
        print(f"[dry-run] {issue['key']}: Verified -> Close Issue")
        continue
    transition(issue["key"], "Close Issue")

Verify: assert the dry-run count and keys match the issue set you intended to close before flipping DRY_RUN to False; if they do not, fix the JQL and re-run the dry run. transition already raises ValueError when the named transition is absent for an issue's workflow, so a workflow mismatch fails loud rather than silently skipping.

CI integration

Auto-file a bug from a test failure:

# .github/workflows/test.yml (excerpt)
- name: Run tests
  id: tests
  run: pytest --junitxml=results.xml
  continue-on-error: true

- name: File Jira bug on failure
  if: steps.tests.outcome == 'failure'
  env:
    JIRA_BASE: ${{ secrets.JIRA_BASE }}
    JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
    JIRA_TOKEN: ${{ secrets.JIRA_TOKEN }}
  run: python scripts/file-jira-bug.py results.xml

Where file-jira-bug.py parses the JUnit XML, extracts the failure, deduplicates, and creates / comments per the helpers above.

Verify: assert the create call returned HTTP 2xx and a non-empty issue key before the step reports success. On 400, the description was likely plain text instead of ADF or a required field is missing - fix the payload and re-run. On 429 (rate limit), back off and retry rather than failing the build. If it still fails, leave the test result red so the filing gap stays visible instead of being swallowed.

Other trackers

The same workflow shape on the other three platforms, each with its own auth, create, transition, search, worked example, anti-patterns, and CI wiring:

• Linear - references/linear.md: GraphQL-only API; issueCreate / issueUpdate mutations; per-team workflowStates resolved by lifecycle type (never display name); priority enum where 1 = Urgent; personal-key vs OAuth Bearer header difference.
• GitHub Issues - references/github-issues.md: two states only; the canonical-lifecycle-to-labels mapping; state_reason transitions (completed / not_planned / duplicate / reopened); Projects v2 GraphQL and the gh CLI.
• Azure DevOps - references/azuredevops.md: JSON Patch work-item mutations (application/json-patch+json); WIQL triage / dedupe queries; process-template state names; optimistic concurrency via test /rev; PR / build artifact links; az boards CLI.

Anti-patterns

Anti-pattern	Why it fails	Fix
Hard-coding transition IDs / state names	Workflow or process-template updates break the runner silently	Discover at runtime (Jira GET /transitions, Linear workflowStates by type, ADO process template)
Plain-text description in Jira	API returns 400 - Jira v3 requires ADF	Wrap as {"type": "doc", "version": 1, "content": [...]}
No deduplication before create	Each retry of a flaky test creates a new bug	Search by summary first; comment on existing
Severity as built-in priority	Conflates two axes (severity-vs-priority-reference)	Use a custom Severity field or severity-* labels
Storing the API token in code	Token leak	Use environment variables / secret stores
Polling metadata endpoints on every call	Rate-limited	Cache per workflow scheme, refresh on 4xx
Bulk transitions without dry-run	Cannot easily reverse if wrong state	Always run in dry-run mode first; log all changes

Limitations

• Workflow is per-project / per-team / per-process. A transition or state name in one project may not exist in another - handle "not found" gracefully on every platform.
• Custom fields are tenant-specific. Jira field IDs (customfield_10039) and ADO severity availability vary; discover at deploy time.
• Rich text differs per platform. Jira needs full ADF; Linear takes Markdown; GitHub takes Markdown; ADO takes HTML. Test code-block / table rendering per platform.
• Rate limits everywhere. Jira per-minute, Linear ~1500 req/15 min, GitHub search 30 req/min unauthenticated, ADO per-user throttling - bulk operations need throttling and retry-with-backoff.
• Query injection. JQL text ~, WIQL CONTAINS WORDS, and GitHub search all interpolate user text - escape quotes and reserved characters.

References

• Jira Cloud REST API v3 issues - developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/.
• Jira Cloud authentication - developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis.
• ADF spec - developer.atlassian.com/cloud/jira/platform/apis/document/structure.
• JQL syntax - confluence.atlassian.com/jiracoreserver/advanced-searching.
• Per-platform deep dives: references/jira.md, references/linear.md, references/github-issues.md, references/azuredevops.md - each carries its own platform-doc citations.
• Sibling reference: severity-vs-priority-reference (classification, lifecycle states, taxonomy).
• Fed by: the from-CI-failure spec workflow in bug-report-template (qa-bug-repro).
• Sibling-plugin neighbour: test-management-sync (in the qa-test-reporting plugin) - different scope (test-result posting; not bug workflow).