github-issue-creator

name

github-issue-creator

description

Create GitHub issues for the current repository with proper title, description, labels, assignees, milestones, and project assignment. Supports issue templates, bulk creation, and markdown formatting. Use when user requests to create, file, open, or submit GitHub issues, report bugs, request features, or track tasks in GitHub. Trigger phrases include "create GitHub issue", "file a bug", "open an issue for [topic]", "create feature request", or when documenting issues that need to be tracked.

GitHub Issue Creator

Overview

This skill creates GitHub issues for the current repository with comprehensive metadata including title, description, labels, assignees, milestones, and project assignments. It supports both single and bulk issue creation, uses GitHub issue templates when available, and integrates with GitKraken for seamless issue management.

When to Use This Skill

Use this skill when:

• Creating bug reports from code analysis or user feedback
• Filing feature requests or enhancement proposals
• Documenting technical debt or refactoring needs
• Creating task tracking issues for project work
• Bulk creating issues from planning documents or backlogs
• Converting meeting notes or requirements into tracked issues
• Creating issues with proper templates and metadata
• Linking issues to projects, milestones, or epics

Trigger Phrases

• "Create a GitHub issue for [topic]"
• "File a bug report about [problem]"
• "Open an issue to track [task]"
• "Create feature request for [feature]"
• "Submit an issue about [topic]"
• "Create issues from this list"
• "File a bug for this error"
• "Create task issues for the sprint"

Core Workflow

Step 1: Gather Issue Information

Required Information:

• Title: Clear, concise issue title (50-80 characters recommended)
• Description: Detailed issue body with context and details

Optional Metadata:

• Labels: Categorization tags (bug, enhancement, documentation, etc.)
• Assignees: GitHub usernames to assign
• Milestone: Target milestone or release version
• Project: GitHub project board to add the issue to
• Priority: Priority level (can be a label or in description)
• Issue Type: Bug, Feature, Task, Documentation, etc.

Information Sources:

1. User Direct Input: User provides title and description
2. Code Analysis: Analyze code context if creating bug from code
3. Error Messages: Format stack traces and error details
4. Templates: Use repository issue templates if available
5. Similar Issues: Check for duplicates before creating

Step 2: Check Repository Context

Before creating the issue, gather repository information:

Get Repository Details:

// Use GitKraken tools to get repo info
const repoInfo = {
  organization: "extracted from git remote",
  repository: "extracted from git remote",
  defaultBranch: "main or master",
  hasIssueTemplates: "check .github/ISSUE_TEMPLATE/"
};

Check for Issue Templates:

Look for templates in:

• .github/ISSUE_TEMPLATE/bug_report.md
• .github/ISSUE_TEMPLATE/feature_request.md
• .github/ISSUE_TEMPLATE/task.md
• .github/ISSUE_TEMPLATE.md (legacy)

If templates exist, use them as a base for issue structure.

Verify Labels and Milestones:

• Query existing labels in the repository
• Check available milestones
• Validate assignee usernames exist

Step 3: Format Issue Content

Title Formatting:

• Keep concise (50-80 characters)
• Start with action verb for tasks ("Add", "Fix", "Update")
• Include context for bugs ("Error in X when Y")
• Use clear, searchable language

Title Examples:

✅ Fix: Customer merge fails with duplicate addresses
✅ Add: Export to Excel functionality for sales reports
✅ Update: Dataverse sync error handling logic
✅ Docs: API integration guide for external developers
❌ Bug (too vague)
❌ Need to fix the thing that broke (unclear)

Description Structure:

Use markdown formatting for clarity:

## Description
Clear explanation of the issue, feature, or task.

## Current Behavior (for bugs)
What currently happens when the issue occurs.

## Expected Behavior (for bugs/features)
What should happen instead.

## Steps to Reproduce (for bugs)
1. Step one
2. Step two
3. Step three

## Code Context (if applicable)
```al
// Relevant code snippet with file reference
// File: src/Codeunit/CustomerManagement.Codeunit.al
procedure MergeCustomers(SourceCustomer: Record Customer; TargetCustomer: Record Customer)
begin
    // TODO: Add validation here
end;

Environment

• AL Extension: [version]
• Business Central: [version]
• Environment: SaaS/OnPrem

Additional Context

Any other relevant information, screenshots, or references.

Acceptance Criteria (for features/tasks)

• Criterion 1
• Criterion 2
• Criterion 3

Related Issues

• Related to #123
• Depends on #456
• Blocks #789

**Label Selection:**

Common labels to use:
- **Type**: `bug`, `enhancement`, `feature`, `task`, `documentation`
- **Priority**: `priority:critical`, `priority:high`, `priority:medium`, `priority:low`
- **Status**: `needs-triage`, `in-progress`, `blocked`, `ready`
- **Area**: `api`, `integration`, `dataverse`, `performance`, `security`
- **Size**: `size:XS`, `size:S`, `size:M`, `size:L`, `size:XL`

### Step 4: Create the Issue Using GitKraken

Use the GitKraken MCP tool to create the issue:

**Tool: `mcp_gitkraken_issues_create`**

```typescript
// Example issue creation
await mcp_gitkraken_issues_create({
  provider: "github",
  repository_organization: "organization-name",
  repository_name: "repo-name",
  title: "Fix: Customer merge fails with duplicate addresses",
  body: "## Description\n\nThe customer merge process fails when...",
  labels: ["bug", "priority:high", "area:customer-management"],
  assignees: ["username"],
  milestone: "v1.5.0"
});

Note: The tool doesn't exist yet in the available tools, so we'll need to use an alternative approach or request the tool be added.

Alternative: Use GitHub CLI or API

If GitKraken tool is not available, use GitHub CLI:

# Create issue with gh CLI
gh issue create `
  --title "Fix: Customer merge fails with duplicate addresses" `
  --body "## Description`n`nThe customer merge process fails when..." `
  --label "bug,priority:high" `
  --assignee "username" `
  --milestone "v1.5.0" `
  --project "Sprint 5"

Step 5: Confirm and Report

After creating the issue:

1. Capture Issue Details:

   • Issue number
   • Issue URL
   • Issue ID

2. Report to User:

   Created GitHub issue #123: Fix: Customer merge fails with duplicate addresses
   URL: https://github.com/org/repo/issues/123
   Labels: bug, priority:high, area:customer-management
   Assigned to: username
   

3. Link to Code (if applicable):

   • If creating from code context, suggest adding issue reference in code comment
   • Suggest creating a branch for the issue: fix/123-customer-merge-duplicate-addresses

Advanced Features

Bulk Issue Creation

When user provides a list of issues to create:

Input Format:

1. Fix customer merge with duplicate addresses [bug] [high]
2. Add Excel export for sales reports [enhancement] [medium]
3. Update API documentation for Dataverse integration [documentation] [low]

Process:

1. Parse list and extract title, type, and priority
2. Create each issue sequentially with appropriate metadata
3. Report summary of created issues

Output:

Created 3 GitHub issues:
- #101: Fix customer merge with duplicate addresses (bug)
- #102: Add Excel export for sales reports (enhancement)
- #103: Update API documentation for Dataverse integration (documentation)

Issue Templates

Using Built-in Templates:

If the repository has issue templates:

1. Read template file
2. Parse frontmatter metadata (labels, assignees, etc.)
3. Present template structure to fill in
4. Create issue with template format

Template Example:

---
name: Bug Report
about: Report a bug or unexpected behavior
title: "[BUG] "
labels: bug, needs-triage
assignees: ''
---

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. See error

**Expected behavior**
A clear and concise description of what you expected to happen.

**Environment:**
- AL Extension Version: [e.g. 1.0.0]
- Business Central Version: [e.g. BC 23.0]

Issue from Code Analysis

When creating an issue based on code analysis:

Workflow:

1. Analyze Code Context:

   • Identify problematic code section
   • Extract function/procedure signature
   • Note file path and line numbers

2. Generate Issue Content:

   ## Issue Found in Code
   
   **Location**: [src/Codeunit/CustomerManagement.Codeunit.al:45-67](src/Codeunit/CustomerManagement.Codeunit.al#L45-L67)
   
   **Code Context**:
   ```al
   procedure MergeCustomers(SourceCustomer: Record Customer; TargetCustomer: Record Customer)
   begin
       // Missing validation for duplicate addresses
       TransferAddresses(SourceCustomer, TargetCustomer);
   end;
   

   Problem: Missing validation before merging customers with duplicate addresses

   Suggested Fix: Add validation to check for duplicate addresses before merge

3. Add Code Owner as Assignee (if CODEOWNERS file exists)

Issue from Error Messages

When creating an issue from an error or exception:

Format Error Information:

## Error Details

**Error Message**: 

Customer with No. 'C000001' cannot be merged because it has duplicate addresses

**Stack Trace**:

at BCS.CustomerManagement.MergeCustomers (CustomerManagement.Codeunit.al:52) at BCS.CustomerMergePage.OnAction (CustomerMergePage.Page.al:23)

**Reproduction**:
1. Navigate to Customer List
2. Select customer C000001
3. Click "Merge with..." action
4. Select target customer with existing address
5. Error occurs

**Environment**:
- Business Central SaaS
- AL Extension: BCS Dataverse Integration v1.0.0

Duplicate Detection

Before creating, check for similar existing issues:

Search Strategy:

1. Search for issues with similar titles
2. Search for issues with same labels
3. Check recently closed issues (might be reopened)

Workflow:

// Search for similar issues
const similarIssues = await searchIssues({
  query: `repo:org/repo is:issue "${issueTitle}"`,
  state: "all"
});

if (similarIssues.length > 0) {
  // Inform user about potential duplicates
  console.log("Found similar issues:");
  similarIssues.forEach(issue => {
    console.log(`- #${issue.number}: ${issue.title} (${issue.state})`);
  });
  
  // Ask if they want to proceed
  const proceed = await confirmWithUser("Create issue anyway?");
  if (!proceed) return;
}

Implementation Steps

Step 1: Verify GitHub Authentication

# Check if GitHub CLI is installed and authenticated
gh auth status

# If not authenticated, prompt user to authenticate
gh auth login

Step 2: Get Repository Information

# Get current repository details
$repoInfo = gh repo view --json owner,name,defaultBranchRef

# Get repository labels
$labels = gh label list --json name,description

# Get milestones
$milestones = gh milestone list --json title,number

Step 3: Prepare Issue Data

Based on user input or context:

$issueData = @{
    title = "Fix: Customer merge fails with duplicate addresses"
    body = @"
## Description
The customer merge process fails when both customers have duplicate addresses...

## Steps to Reproduce
1. Navigate to Customer List
2. Select customer with existing addresses
3. Click "Merge with..." action
4. Error occurs

## Expected Behavior
Should validate and handle duplicate addresses gracefully.
"@
    labels = @("bug", "priority:high", "area:customer-management")
    assignees = @("username")
    milestone = "v1.5.0"
}

Step 4: Create Issue via GitHub CLI

# Create the issue
$issueUrl = gh issue create `
    --title $issueData.title `
    --body $issueData.body `
    --label ($issueData.labels -join ",") `
    --assignee ($issueData.assignees -join ",") `
    --milestone $issueData.milestone

# Parse issue number from URL
if ($issueUrl -match '/(\d+)$') {
    $issueNumber = $Matches[1]
    Write-Host "Created issue #$issueNumber"
    Write-Host "URL: $issueUrl"
}

Step 5: Add to Project (if specified)

# Add issue to project board
gh project item-add $projectNumber --owner $orgName --url $issueUrl

Best Practices

Issue Title Guidelines

✅ Good Titles:

• "Fix: API timeout when syncing large datasets"
• "Add: Bulk update functionality for customer records"
• "Update: Error handling in Dataverse synchronization"
• "Docs: Installation guide for on-premise deployments"

❌ Bad Titles:

• "Bug" (too vague)
• "Fix this" (no context)
• "The thing doesn't work" (unclear)
• "URGENT!!!" (use priority labels instead)

Description Best Practices

1. Be Specific: Include exact error messages, file names, line numbers
2. Add Context: Explain when the issue occurs and its impact
3. Include Reproduction Steps: Make it easy for others to reproduce
4. Suggest Solutions: If you have ideas, include them
5. Link Related Issues: Reference related or dependent issues
6. Add Visuals: Screenshots or diagrams when helpful

Label Strategy

Use Consistent Labels:

• bug - Something isn't working
• enhancement - New feature or improvement
• documentation - Documentation improvements
• question - Further information is requested
• wontfix - This will not be worked on
• duplicate - This issue already exists
• good first issue - Good for newcomers
• help wanted - Extra attention is needed

Priority Labels:

• priority:critical - Blocks production, needs immediate fix
• priority:high - Important, should be addressed soon
• priority:medium - Normal priority
• priority:low - Nice to have, not urgent

Assignee Guidelines

• Assign to person responsible for the area
• Don't assign if unsure (let team triage)
• For bugs, assign to original code author if known
• For features, assign to product owner or tech lead

Examples

Example 1: Bug Report from Code

User Request: "Create an issue for the validation bug in customer merge"

Process:

1. Analyze code context
2. Format bug report with code reference
3. Create issue

Created Issue:

# Fix: Missing validation in customer merge causes data corruption

## Description
The `MergeCustomers` procedure in CustomerManagement codeunit lacks validation for duplicate addresses, leading to data corruption when merging customers with overlapping address records.

## Location
[src/Codeunit/BCSCRMSynchManagement.Codeunit.al:145-167](src/Codeunit/BCSCRMSynchManagement.Codeunit.al#L145-L167)

## Current Behavior
When merging two customers that have the same address (e.g., same street, city, postal code), the merge operation creates duplicate address entries linked to the target customer.

## Steps to Reproduce
1. Create Customer A with address "123 Main St, Boston, MA 02101"
2. Create Customer B with the same address
3. Navigate to Customer A
4. Use "Merge with..." action to merge with Customer B
5. Check target customer's addresses - duplicates exist

## Expected Behavior
The merge operation should:
- Detect duplicate addresses before merging
- Prompt user to choose which address to keep
- Prevent duplicate address records

## Code Context
```al
procedure MergeCustomers(SourceCustomer: Record Customer; TargetCustomer: Record Customer)
begin
    // TODO: Add duplicate address validation here
    TransferAddresses(SourceCustomer, TargetCustomer);
    TransferTransactions(SourceCustomer, TargetCustomer);
    ArchiveCustomer(SourceCustomer);
end;

Suggested Fix

Add validation procedure:

local procedure ValidateDuplicateAddresses(SourceRec: Record Customer; TargetRec: Record Customer): Boolean
var
    SourceAddr: Record "Customer Address";
    TargetAddr: Record "Customer Address";
begin
    // Check for duplicate addresses and prompt user
end;

Impact

• Severity: High (causes data corruption)
• Affected Users: All users performing customer merges
• Workaround: Manually clean up duplicate addresses after merge

Environment

• AL Extension: BCS Dataverse Integration v1.0.0
• Business Central: Version 23.0 (SaaS)

**Issue Metadata:**
- Labels: `bug`, `priority:high`, `area:customer-management`, `data-integrity`
- Assignee: Code owner from CODEOWNERS
- Milestone: Next patch release

### Example 2: Feature Request

**User Request**: "Create a feature request for Excel export on department list"

**Created Issue:**
```markdown
# Add: Excel export functionality for department list

## Description
Add the ability to export the department list to Excel format with all visible columns and applied filters.

## Business Value
Users frequently need to share department data with external stakeholders who don't have access to Business Central. Excel export enables:
- Sharing data with finance team for budgeting
- Creating reports for management
- Offline analysis and manipulation

## Proposed Solution

### User Experience
1. User opens Department List page
2. User applies any desired filters
3. User clicks "Export to Excel" action
4. System generates Excel file with:
   - All visible columns
   - Applied filters in header row
   - Formatted with company branding
5. File is downloaded to user's device

### Technical Implementation
- Create new report object based on Department table
- Add "Export to Excel" action to Department List page
- Use Excel Buffer codeunit for formatting
- Include column headers and filters

## Acceptance Criteria
- [ ] Export action appears on Department List page
- [ ] Export includes all visible columns
- [ ] Export respects current filters
- [ ] Excel file has proper formatting (headers, borders)
- [ ] Export handles large datasets (1000+ records)
- [ ] File naming convention: "Departments_YYYYMMDD_HHMMSS.xlsx"
- [ ] Success message shown after export

## Similar Features
- Customer List already has Excel export
- Item List has similar functionality
- Should follow same UX pattern

## Priority
Medium - Requested by multiple users but has workaround (copy/paste)

## Estimated Effort
Small (4-8 hours) - Can reuse existing Excel export patterns

Issue Metadata:

• Labels: enhancement, priority:medium, area:department-management, size:S
• Milestone: v1.5.0
• Project: Feature Backlog

Example 3: Task Issue

User Request: "Create task issues for API implementation sprint"

Created Issues:

Issue #1:

# Task: Design API endpoints for department CRUD operations

## Description
Design RESTful API endpoints for department create, read, update, and delete operations following BC API v2.0 conventions.

## Deliverables
- [ ] API endpoint specifications document
- [ ] Request/response payload schemas
- [ ] Error response formats
- [ ] Authentication/authorization requirements

## Technical Details
- Base URL: `/api/bcsdemo/v1.0/departments`
- Methods: GET, POST, PATCH, DELETE
- Follow OData v4 conventions
- Include filtering, sorting, paging

## Dependencies
None - This is the first task

## Time Estimate
4 hours

Issue #2:

# Task: Implement Department API page object

## Description
Create API page object for Department table with proper field mappings and navigation properties.

## Deliverables
- [ ] BCSAPIDepartment.Page.al file created
- [ ] All required fields mapped
- [ ] Navigation properties configured
- [ ] Unit tests created

## Technical Details
- Use API page type
- PageType = API
- APIPublisher = 'bcsdemo'
- APIGroup = 'department'
- APIVersion = 'v1.0'
- EntityName = 'department'
- EntitySetName = 'departments'

## Dependencies
- Blocks: Issue #XXX (API documentation)
- Depends on: Issue #YYY (API design) ✅

## Time Estimate
6 hours

Issue Metadata:

• Labels: task, area:api, sprint:5
• Assignee: Current developer
• Milestone: Sprint 5
• Project: API Implementation

Error Handling

Authentication Errors

# Check authentication before creating issue
try {
    gh auth status
} catch {
    Write-Error "GitHub CLI not authenticated. Run: gh auth login"
    return
}

Repository Not Found

# Verify repository exists
try {
    $repo = gh repo view --json owner,name
} catch {
    Write-Error "Not a GitHub repository or no access. Verify repository URL."
    return
}

Invalid Label or Milestone

# Validate labels exist
$existingLabels = gh label list --json name | ConvertFrom-Json
$invalidLabels = $labels | Where-Object { $_ -notin $existingLabels.name }

if ($invalidLabels) {
    Write-Warning "Labels not found: $($invalidLabels -join ', ')"
    Write-Host "Creating missing labels..."
    foreach ($label in $invalidLabels) {
        gh label create $label --description "Auto-created label"
    }
}

Rate Limiting

# Handle rate limiting
try {
    $issue = gh issue create --title $title --body $body
} catch {
    if ($_.Exception.Message -match "rate limit") {
        Write-Error "GitHub API rate limit exceeded. Try again later."
        # Show rate limit status
        gh api rate_limit
    }
}

Integration with Other Skills

With github-todo-issue-creator

When used together:

• TODO scanner identifies items
• github-issue-creator creates structured issues
• Provides richer issue formatting and metadata

With Project Management

Link created issues to:

• GitHub Projects for sprint planning
• Milestones for release tracking
• Labels for categorization and filtering

Summary

This skill provides comprehensive GitHub issue creation with:

• ✅ Single and bulk issue creation
• ✅ Rich markdown formatting
• ✅ Label, assignee, and milestone support
• ✅ Issue template integration
• ✅ Duplicate detection
• ✅ Code context inclusion
• ✅ Error handling and validation

The skill streamlines issue tracking and ensures consistent, well-formatted issues across the repository.