jira-git-integration

name: jira-git-integration description: Generic JIRA + Git workflow utilities for ticket management, branch creation, and integration license: Apache-2.0 compatibility: opencode metadata: audience: developers workflow: jira-git-integration

What I do

I provide JIRA + Git integration utilities that can be used across multiple workflows:

1. Get JIRA Resources: Detect and retrieve Atlassian cloud ID, visible projects, and accessible resources
2. Get JIRA User Info: Retrieve current user's account ID for ticket assignment
3. Create JIRA Tickets: Create new tasks, stories, or bugs in specified JIRA projects
4. Add JIRA Comments: Add comments to existing JIRA tickets with Markdown formatting
5. Upload Images to JIRA: Upload local images as JIRA attachments and retrieve attachment URLs
6. Generate JIRA Branch Names: Create consistent branch names from JIRA tickets
7. Fetch JIRA Issue Details: Retrieve ticket information including status, assignee, description

When to use me

Use this framework when:

• You need JIRA integration in a workflow
• You're creating a skill that requires JIRA ticket management
• You need to upload images to JIRA tickets
• You want to ensure consistent branch naming across JIRA workflows
• You need to add comments or attachments to JIRA tickets

This is a framework skill - it provides JIRA utilities that other skills use.

Core Workflow Steps

Step 1: Get Accessible Atlassian Resources

Purpose: Retrieve cloud ID and list of accessible Atlassian resources

Tools Used: atlassian_getAccessibleAtlassianResources

# Get accessible resources (includes cloud IDs)
atlassian_getAccessibleAtlassianResources

Expected Output:

[
  {
    "id": "23594c42-08ff-4d2a-8065-6756e3590c37",
    "url": "https://company.atlassian.net",
    "name": "company",
    "scopes": ["read:jira-work", "write:jira-work", "read:confluence", "write:confluence"]
  }
]

Extract Cloud ID: Store the id field for use in subsequent JIRA operations

Step 2: Get JIRA User Information

Purpose: Retrieve current user's account ID for ticket assignment

Tools Used: atlassian_atlassianUserInfo

# Get current user info
atlassian_atlassianUserInfo

Expected Output:

{
  "account_id": "712020:1fe13d6b-e3ff-4455-9349-39a1f243e9bb",
  "email": "user@company.com",
  "name": "John Doe",
  "account_status": "active"
}

Extract Account ID: Store the account_id field for assigning tickets

Step 3: Get Visible JIRA Projects

Purpose: List all JIRA projects the user has access to

Tools Used: atlassian_getVisibleJiraProjects

# Get visible projects
atlassian_getVisibleJiraProjects --cloudId <CLOUD_ID>

Expected Output:

{
  "values": [
    {
      "key": "IBIS",
      "name": "Project Name",
      "id": "10205",
      "issueTypes": [
        {
          "name": "Task",
          "id": "10222"
        },
        {
          "name": "Story",
          "id": "10220"
        },
        {
          "name": "Bug",
          "id": "10223"
        }
      ]
    }
  ]
}

Extract Project Key: Store the key field (e.g., IBIS) for use in ticket creation

Step 4: Create JIRA Ticket

Purpose: Create a new ticket in specified JIRA project

Tools Used: atlassian_createJiraIssue

# Create new ticket
atlassian_createJiraIssue \
  --cloudId <CLOUD_ID> \
  --projectKey <PROJECT_KEY> \
  --issueTypeName <ISSUE_TYPE> \
  --summary "<Ticket Title>" \
  --description "<Ticket Description>" \
  --assignee_account_id <USER_ACCOUNT_ID>

Parameters:

• cloudId: Atlassian cloud ID (from Step 1)
• projectKey: JIRA project key (e.g., IBIS)
• issueTypeName: Issue type name (e.g., Task, Story, Bug)
• summary: Short title for the ticket
• description: Detailed description in Markdown format
• assignee_account_id: User's account ID (from Step 2, optional)

Description Template:

## Description
<Detailed description of the work>

## Type
<Task | Story | Bug>

## Context
<Additional background information>

## Acceptance Criteria
- [ ] Criteria 1
- [ ] Criteria 2
- [ ] Criteria 3

## Files to Modify
1. `path/to/file1.ts` - Description
2. `path/to/file2.tsx` - Description

## Notes
<Additional notes or constraints>

Expected Output:

{
  "id": "12345",
  "key": "IBIS-101",
  "self": "https://api.atlassian.com/ex/jira/.../issue/12345"
}

Extract Ticket Key: Store the key field (e.g., IBIS-101) for reference

Step 5: Add Comment to JIRA Ticket

Purpose: Add a comment to an existing JIRA ticket

Tools Used: atlassian_addCommentToJiraIssue

# Add comment
atlassian_addCommentToJiraIssue \
  --cloudId <CLOUD_ID> \
  --issueIdOrKey <TICKET_KEY> \
  --commentBody "<Comment Content>"

Parameters:

• cloudId: Atlassian cloud ID
• issueIdOrKey: Ticket key (e.g., IBIS-101)
• commentBody: Comment content in Markdown format

Comment Templates:

PR Reference Comment:

## Pull Request Created

**PR**: #<PR_NUMBER> - <PR_TITLE>
**URL**: <PR_URL>
**Branch**: <branch-name>

### Changes Summary
<Brief description of changes>

### Files Modified
<list of key files changed>

### Quality Checks
- Linting: ✅ Passed
- Build: ✅ Passed
- Tests: ✅ Passed

### Review Request
@reviewer1 @reviewer2

Implementation Update Comment:

## Implementation Started

Branch: <branch-name>
Status: In Progress

### Next Steps
1. <Step 1>
2. <Step 2>
3. <Step 3>

Image-Embedded Comment:

## Diagrams/Visuals

### Workflow Diagram
![Workflow Diagram](https://company.atlassian.net/secure/attachment/12345/workflow.png)

### Architecture
![System Architecture](https://company.atlassian.net/secure/attachment/12346/architecture.png)

Step 6: Upload Image to JIRA

Purpose: Upload a local image file as a JIRA attachment

Tools Used: atlassian_addAttachmentToJiraIssue

# Upload image
atlassian_addAttachmentToJiraIssue \
  --cloudId <CLOUD_ID> \
  --issueIdOrKey <TICKET_KEY> \
  --attachment <IMAGE_FILE_PATH>

Parameters:

• cloudId: Atlassian cloud ID
• issueIdOrKey: Ticket key (e.g., IBIS-101)
• attachment: Path to local image file (e.g., /tmp/workflow.png)

Expected Output:

{
  "id": "10001",
  "filename": "workflow.png",
  "content": "image/png",
  "size": 12345,
  "self": "https://api.atlassian.com/ex/jira/.../attachment/10001"
  "thumbnail": "https://company.atlassian.net/secure/thumbnail/12345/workflow.png"
}

Extract Attachment URL: The self field provides the URL for embedding in comments

Attachment URL Format:

https://company.atlassian.net/secure/attachment/<ATTACHMENT_ID>/<FILENAME>

Usage in Comments:

![Workflow Diagram](https://company.atlassian.net/secure/attachment/10001/workflow.png)

Step 7: Generate JIRA Branch Name

Purpose: Create a consistent branch name from a JIRA ticket key

Branch Naming Conventions:

Implementation:

# Generate branch name from ticket key
TICKET_KEY="IBIS-101"

# Simple format
BRANCH_NAME="${TICKET_KEY}"  # IBIS-101

# Feature format
BRANCH_NAME="feature/${TICKET_KEY}"  # feature/IBIS-101

# Descriptive feature format
BRANCH_NAME="feature/${TICKET_KEY}-add-dark-mode"  # feature/IBIS-101-add-dark-mode

# Create and checkout branch
git checkout -b "${BRANCH_NAME}"

Branch Naming Best Practices:

• Use lowercase
• Replace spaces with hyphens
• Include ticket key for traceability
• Keep branch names under 72 characters
• Follow git branch naming conventions

Step 8: Get JIRA Issue Details

Purpose: Retrieve detailed information about a JIRA ticket

Tools Used: atlassian_getJiraIssue

# Get issue details
atlassian_getJiraIssue \
  --cloudId <CLOUD_ID> \
  --issueIdOrKey <TICKET_KEY>

Parameters:

• cloudId: Atlassian cloud ID
• issueIdOrKey: Ticket key (e.g., IBIS-101)

Expected Output:

{
  "key": "IBIS-101",
  "fields": {
    "summary": "Implement new feature",
    "status": {
      "name": "In Progress"
    },
    "assignee": {
      "accountId": "712020:1fe13d6b-e3ff-4455-9349-39a1f243e9bb",
      "displayName": "John Doe"
    },
    "description": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "text": "Detailed description..."
            }
          ]
        }
      ]
    }
    }
  }
}

Extract Information:

• Ticket status
• Assignee information
• Description content
• Priority, labels, etc.

Image Handling Strategy

Image Detection Patterns

Search for images in these locations:

# Common image locations
./diagrams/**/*.png
./diagrams/**/*.svg

# Recent images in tmp
/tmp/*.png
/tmp/*.jpg

# Documentation images
./docs/images/**/*.png
./assets/images/**/*.png

# Workflow-related (by filename pattern)
**/*workflow*.png
**/*diagram*.png
**/*flow*.png
**/*architecture*.png
**/*sequence*.png

Image Categorization

# Determine if image needs upload
if [[ "$image_path" =~ ^https?:// ]]; then
  # It's a URL - check if accessible
  if curl -s -o /dev/null -w "%{http_code}" "$image_path" | grep -q "200"; then
    TYPE="accessible_url"
  else
    TYPE="inaccessible_url"
  fi
else
  # It's a file path
  if [[ -f "$image_path" ]]; then
    TYPE="local_file"
  else
    TYPE="not_found"
  fi
fi

Handling Each Image Type

Step 9: Transition JIRA Ticket Status

Purpose: Update JIRA ticket status after PR merge

Tools Used: atlassian_getTransitionsForJiraIssue, atlassian_transitionJiraIssue

Usage:

# Get available transitions
TRANSITIONS=$(atlassian_getTransitionsForJiraIssue \
  --cloudId <CLOUD_ID> \
  --issueIdOrKey <TICKET_KEY>)

# Find "Done" or "Closed" transition
TARGET_TRANSITION_ID=$(echo "$TRANSITIONS" | jq -r '.transitions[] | select(.to.name == "Done" or .to.name == "Closed") | .id' | head -1)

# Execute transition
atlassian_transitionJiraIssue \
  --cloudId <CLOUD_ID> \
  --issueIdOrKey <TICKET_KEY> \
  --transition '{"id": "<TRANSITION_ID>"}')

When to Use:

• PR has been successfully merged
• Work is complete and ticket should be closed
• Automating workflow to eliminate manual status updates

Integration:

• Use with jira-status-updater skill for complete automation
• Use with pr-creation-workflow for integrated PR + status updates
• Use with git-pr-creator for optional status updates after manual merge

Best Practices

• Cloud ID: Always retrieve cloud ID once per session
• User Info: Cache user account ID for assignment operations
• Project Keys: Use project keys (e.g., IBIS) consistently
• Ticket References: Always use ticket keys (e.g., IBIS-101) for traceability
• Branch Naming: Use consistent branch naming with ticket keys
• Image Uploads: Upload local/temporary images, don't link to local paths
• Comment Formatting: Use Markdown for rich formatting in JIRA comments
• Error Handling: Check for JIRA API errors and provide clear messages
• Permissions: Verify user has appropriate permissions for operations

Common Issues

Cloud ID Not Found

Issue: Cannot determine Atlassian cloud ID

Solution:

# Use getAccessibleAtlassianResources to find cloud ID
atlassian_getAccessibleAtlassianResources

Project Not Found

Issue: JIRA project key is invalid or inaccessible

Solution:

# List visible projects to find correct key
atlassian_getVisibleJiraProjects --cloudId <CLOUD_ID>

User Not Assigned

Issue: Ticket not assigned to current user

Solution:

# Get user account ID
atlassian_atlassianUserInfo

# Create ticket with assignee
atlassian_createJiraIssue --assignee_account_id <ACCOUNT_ID>

Image Upload Fails

Issue: atlassian_addAttachmentToJiraIssue returns error

Solution:

• Verify file path is correct
• Check file size limits (JIRA typically limits to 10-100MB)
• Ensure you have permission to add attachments
• Verify file is not corrupted

Branch Name Conflicts

Issue: Branch with same name already exists

Solution:

# Force create new branch
git checkout -B <branch-name>

# Or switch to existing branch
git checkout <existing-branch>

Troubleshooting Checklist

Before JIRA operations:

• Cloud ID is available
• User account ID is retrieved
• Project key is valid
• Issue type is valid for project
• User has appropriate permissions

After ticket creation:

• Ticket number/key is captured
• Ticket URL is accessible
• Ticket is assigned to correct user
• Branch name is generated correctly

After comment/attachment operations:

• Comment is added successfully
• Images are uploaded to JIRA
• Attachment URLs are accessible
• Comments display formatting correctly

Related Commands

# Get visible JIRA projects
atlassian_getVisibleJiraProjects --cloudId <CLOUD_ID>

# Get JIRA issue details
atlassian_getJiraIssue --cloudId <CLOUD_ID> --issueIdOrKey <TICKET_KEY>

# Add comment to JIRA issue
atlassian_addCommentToJiraIssue --cloudId <CLOUD_ID> --issueIdOrKey <TICKET_KEY> --commentBody "<markdown>"

# Upload attachment to JIRA
atlassian_addAttachmentToJiraIssue --cloudId <CLOUD_ID> --issueIdOrKey <TICKET_KEY> --attachment <file-path>

# Create JIRA ticket
atlassian_createJiraIssue --cloudId <CLOUD_ID> --projectKey <PROJECT_KEY> --issueTypeName "Task" --summary "Title" --description "<desc>"

# Get user info
atlassian_atlassianUserInfo

# Get accessible resources
atlassian_getAccessibleAtlassianResources

Relevant Skills

Skills that use this JIRA integration framework:

• git-pr-creator: PR creation with JIRA comments and image uploads
• jira-ticket-plan-workflow: JIRA ticket creation and branch management
• nextjs-pr-workflow: Next.js PR workflow with JIRA integration
• jira-status-updater: Automated JIRA ticket status transitions after PR merge