github-issues-bug-workflow

Overview

GitHub Issues has only two states: open and closed. This is intentionally minimalist. To express the canonical defect lifecycle (bug-lifecycle-reference) teams supplement Issues with labels (severity, priority, status) and optionally Projects v2 (status columns).

This skill wraps the GitHub Issues REST API v2022-11-28 (per docs.github.com/en/rest/issues/issues) for create / update / close / reopen / search, and notes the Projects v2 GraphQL augmentation when richer state is needed.

When to use

• Filing a bug from a CI test failure on a GitHub-hosted project (consumed by bug-report-from-failure).
• Maintaining bug label / status discipline in an open-source project where GitHub Issues is the canonical tracker.
• Backing the duplicate-defect-finder search for GitHub-using teams.

Authoring

Authentication

Per GitHub REST API docs:

export GITHUB_TOKEN="ghp_..."  # personal access token, classic or fine-grained
export GITHUB_REPO="owner/repo"

import requests, os

HEADERS = {
    "Authorization": f"Bearer {os.environ['GITHUB_TOKEN']}",
    "Accept": "application/vnd.github+json",
    "X-GitHub-Api-Version": "2026-03-10",
}
BASE = f"https://api.github.com/repos/{os.environ['GITHUB_REPO']}"

The X-GitHub-Api-Version header is recommended per the API docs to lock the response shape.

Alternative: the gh CLI handles auth via the user's stored credentials:

gh issue create --title "..." --body "..." --label bug,severity:high

Create an issue

POST /repos/{owner}/{repo}/issues per the API docs:

def create_bug(title, body, severity, priority, labels=None):
    payload = {
        "title": title,
        "body": body,
        "labels": (labels or []) + [
            "bug",
            f"severity:{severity}",
            f"priority:{priority}",
        ],
    }
    r = requests.post(f"{BASE}/issues", json=payload, headers=HEADERS)
    r.raise_for_status()
    return r.json()

Required parameter is title. Optional: body, assignees, milestone, labels, type (recently added for issue types).

Label conventions

Since GitHub has no first-class severity / priority field, teams adopt label prefixes:

Adopt them consistently - the bug-report-critic checks that severity + priority labels are both present.

State transitions via PATCH

PATCH /repos/{owner}/{repo}/issues/{issue_number}. The state_reason parameter (per API docs) takes completed | not_planned | reopened | duplicate:

def close(issue_number, reason="completed"):
    """reason: completed | not_planned | duplicate"""
    r = requests.patch(
        f"{BASE}/issues/{issue_number}",
        json={"state": "closed", "state_reason": reason},
        headers=HEADERS,
    )
    r.raise_for_status()
    return r.json()

def reopen(issue_number):
    r = requests.patch(
        f"{BASE}/issues/{issue_number}",
        json={"state": "open", "state_reason": "reopened"},
        headers=HEADERS,
    )
    r.raise_for_status()
    return r.json()

Map canonical lifecycle states via labels + close-reason:

Search

GET /repos/{owner}/{repo}/issues supports filter via query parameters; for richer search use the search endpoint:

def search_issues(q):
    r = requests.get(
        "https://api.github.com/search/issues",
        params={"q": f"repo:{os.environ['GITHUB_REPO']} {q}"},
        headers=HEADERS,
    )
    r.raise_for_status()
    return r.json()["items"]

dupes = search_issues(
    f'type:issue is:open label:bug "{title_safe}" in:title,body'
)

GitHub search has a 30-request-per-minute unauthenticated / higher authenticated rate limit.

Comments

POST /repos/{owner}/{repo}/issues/{issue_number}/comments:

def add_comment(issue_number, body):
    r = requests.post(
        f"{BASE}/issues/{issue_number}/comments",
        json={"body": body}, headers=HEADERS)
    r.raise_for_status()
    return r.json()

Running

Idempotent bug filing

def create_or_attach(title, body):
    dupes = search_issues(f'is:open label:bug "{title}" in:title')
    if dupes:
        add_comment(dupes[0]["number"], f"Recurred: {body[:500]}")
        return dupes[0]["number"]
    issue = create_bug(title, body, severity="medium", priority="p3")
    return issue["number"]

Projects v2 status updates

For richer state (e.g., a Kanban with custom columns), Projects v2 requires GraphQL - the REST API doesn't reach Projects v2:

PROJECTS_MUTATION = """
mutation MoveItem($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
  updateProjectV2ItemFieldValue(
    input: { projectId: $projectId, itemId: $itemId,
             fieldId: $fieldId, value: { singleSelectOptionId: $optionId } }
  ) { projectV2Item { id } }
}
"""
# Discovery of projectId, itemId, fieldId, optionId via the matching queries.

Per docs.github.com/en/issues/planning-and-tracking-with-projects.

gh CLI for scripts

# Create
gh issue create \
  --title "Checkout fails for promo X" \
  --body-file failure.md \
  --label bug,severity:high,priority:p2

# Close with reason
gh issue close 1234 --reason completed
gh issue close 1234 --reason "not planned"

# Search
gh issue list --search 'is:open label:bug "checkout fails"'

Parsing results

Create response includes number (per-repo), html_url (permalink), node_id (GraphQL ID for Projects v2 cross-ref).

Search response includes items array (issues + PRs), total_count, incomplete_results (set to true on partial results due to rate limit).

CI integration

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

- name: File issue on test failure
  if: steps.tests.outcome == 'failure'
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    GITHUB_REPO: ${{ github.repository }}
  run: python scripts/file-github-bug.py results.xml

Use the auto-provided GITHUB_TOKEN for in-repo automation; for cross-repo, use a fine-grained PAT.

Anti-patterns

Limitations

• Open / closed only. Rich lifecycle expressed via labels + Projects requires team discipline; the API doesn't enforce it.
• No native severity / priority fields. Conventions vary across orgs - the runner is portable only if the team adopts the label vocabulary above.
• Projects v2 is GraphQL. REST + GraphQL hybrid; engineers need both.
• type field is new. GitHub recently added issue type; not universally supported across all clients yet.
• Cross-repo dedupe. GitHub Issues are per-repo; cross-repo duplicate detection needs Search API with org: qualifier.

References

• GitHub Issues REST API - docs.github.com/en/rest/issues/issues.
• GitHub Search API - docs.github.com/en/rest/search/search#search-issues-and-pull-requests.
• Projects v2 GraphQL - docs.github.com/en/issues/planning-and-tracking-with-projects.
• gh CLI manual - cli.github.com/manual/gh_issue.
• Sibling references: bug-lifecycle-reference, severity-vs-priority-reference.
• Sibling skills: jira-bug-workflow-runner, linear-bug-workflow-runner.
• Consumed by: bug-report-from-failure, duplicate-defect-finder.