🎯 GitHub Action for Jira Issue Creation

A robust, enterprise-grade GitHub Action for creating Jira issues and sub-tasks with advanced security features, comprehensive input validation, modular architecture, and extensive testing. Built with Python 3.11+ and designed for production environments with zero-trust security principles.

✨ Features

🔒 Security & Validation

• ✅ Input Sanitization: Advanced SQL injection and XSS protection
• ✅ Pattern Validation: Comprehensive malicious pattern detection
• ✅ Secure Authentication: Token-based authentication with secure handling
• ✅ Injection Prevention: Protection against command injection attacks
• ✅ Data Validation: Type-safe input validation with custom error handling

🏗️ Architecture & Quality

• ✅ Modular Design: Clean separation of concerns with dedicated modules
• ✅ Type Safety: Full type hints and runtime validation
• ✅ Error Handling: Structured exception handling with custom error types
• ✅ Testing: Comprehensive test suite with 95%+ coverage
• ✅ CI/CD: Automated testing, linting, and security scanning

Core Issue Management

• ✅ Multi-Type Support: Create Tasks, Bugs, Stories, Sub-tasks, and Epics
• ✅ Smart Sub-task Handling: Automatic parent-child relationship management
• ✅ Flexible Assignee Management: Optional assignee with validation
• ✅ Priority Control: High, Medium, Low priority settings
• ✅ Label Management: Comma-separated label support

Advanced Capabilities

• 🔄 Attachment Support: Upload multiple files to created issues
• 🛡️ Enterprise Error Handling: Comprehensive HTTP status code handling
• 🔍 Input Validation: Robust validation of all parameters
• 📝 GitHub Integration: Automatic step summary updates with issue links
• 🔐 Security: Secure authentication via API tokens

Developer Experience

• 🚀 Easy Setup: Simple workflow integration
• 📋 Manual Trigger: Workflow dispatch for on-demand issue creation
• 🔧 Configurable: Extensive customization options
• 📊 Feedback: Clear success/error messaging
• 📚 Documentation: Comprehensive guides and examples

📋 Project Structure

jira-issue/
├── action.yml                     # Main GitHub Action definition
├── requirements.txt               # Python dependencies
├── LICENSE                        # MIT license
├── README.md                      # This documentation
├── CONTRIBUTING.md                # Contributor guidelines
├── SECURITY.md                    # Security policy
├── CHANGELOG.md                   # Version history
├── .github/
│   ├── dependabot.yml            # 🔄 Dependabot configuration (creates PRs)
│   ├── security.yml              # Security policy configuration
│   └── workflows/
│       ├── test.yml              # 🧪 Quality Assurance (CI/CD)
│       ├── dependabot-auto-merge.yml # 🔀 Auto-merge Dependencies (merges PRs)
│       └── release.yml           # 🚀 Release Management
│   # Note: 🔒 Security Analysis via GitHub's default CodeQL setup
├── src/                          # Python source code
│   ├── __init__.py              # Package initialization
│   ├── main.py                   # Main entry point
│   ├── jira_client.py           # Jira API client
│   ├── validators.py            # Input validation
│   ├── exceptions.py            # Custom exceptions
│   └── utils.py                 # Utility functions
├── tests/                        # Test suite
│   ├── conftest.py              # Test configuration
│   ├── run_tests.py             # Test runner script
│   ├── test_main.py             # Main module tests
│   ├── test_jira_client.py      # Client tests
│   ├── test_validators.py       # Validation tests
│   └── test_utils.py            # Utility tests
└── docs/                         # Documentation
    ├── development.md            # Developer guide  
    ├── examples.md              # Practical examples and use cases
    ├── troubleshooting.md       # Common issues and solutions
    └── SECURITY_CONSTRAINTS.md  # Security validation guidelines

🔒 Security Features

This action implements enterprise-grade security measures with automated monitoring:

🤖 Automated Security

• 🔄 Dependabot Ecosystem:
  • Configuration: .github/dependabot.yml creates weekly dependency update PRs
  • Auto-merge: 🔀 Auto-merge Dependencies workflow safely merges patch/minor updates
  • Smart Grouping: Security updates prioritized, minor updates batched
• 🔍 CodeQL: GitHub's default security analysis with comprehensive query packs
• 🚨 Security Alerts: Real-time vulnerability notifications and automatic fixes
• 🔐 Secret Scanning: Automatic detection and protection of exposed credentials
• 🛡️ Branch Protection: Automated enforcement of security policies

🛡️ Code Protection

• 🛡️ Input Sanitization: Protection against SQL injection, XSS, and command injection
• 🔍 Pattern Detection: Advanced malicious pattern recognition
• 🔐 Secure Authentication: Safe handling of API tokens and credentials
• 📊 Audit Logging: Comprehensive logging for security auditing
• ⚡ Rate Limiting: Built-in protection against API abuse
• 🚨 Error Masking: Sensitive information protection in error messages

See SECURITY.md for detailed security policies and vulnerability reporting.

🚀 Quick Start

Prerequisites

• Jira Access: Jira instance with API access and valid credentials
• GitHub Repository: Repository with Actions enabled
• Permissions: Jira API token with appropriate project permissions
• Python Knowledge: Basic understanding of GitHub Actions workflows

Step 1: Generate Jira API Token

1. Navigate to your Jira profile settings
2. Go to Security → API tokens
3. Click Create API token
4. Provide a meaningful label (e.g., "GitHub Actions")
5. Copy the generated token securely

Step 2: Configure Repository Secrets

Add these secrets in your GitHub repository settings (Settings → Secrets and variables → Actions):

JIRA_USERNAME    - Your Jira username or email address
JIRA_API_TOKEN   - Your generated Jira API token (never your password!)
JIRA_SERVER      - Your Jira server URL (optional, can be input parameter)

Step 3: Create Workflow

Create .github/workflows/create-jira-issue.yml:

name: 🎯 Create Jira Issue

on:
  workflow_dispatch:
    inputs:
      jira_server:
        description: "🌐 Jira server URL (e.g., https://company.atlassian.net)"
        required: true
        default: "https://your-domain.atlassian.net"
      project_key:
        description: "📋 Jira project key (e.g., PROJ, DEV)"
        required: true
      issue_type:
        description: "🏷️ Type of issue to create"
        required: true
        default: "Task"
        type: choice
        options:
          - "Task"
          - "Bug" 
          - "Story"
          - "Sub-task"
          - "Epic"
      issue_summary:
        description: "📝 Brief summary of the issue"
        required: true
      issue_description:
        description: "📄 Detailed description of the issue"
        required: true
      issue_priority:
        description: "⚡ Issue priority level"
        required: false
        default: "Medium"
        type: choice
        options:
          - "High"
          - "Medium"
          - "Low"

jobs:
  create_jira_issue:
    name: 🚀 Create Jira Issue
    runs-on: ubuntu-latest
    
    steps:
      - name: 🎯 Create Jira Issue
        uses: solarekm/jira-issue@v2
        with:
          jira_server: ${{ github.event.inputs.jira_server }}
          jira_username: ${{ secrets.JIRA_USERNAME }}
          jira_api_token: ${{ secrets.JIRA_API_TOKEN }}
          project_key: ${{ github.event.inputs.project_key }}
          issue_type: ${{ github.event.inputs.issue_type }}
          issue_summary: ${{ github.event.inputs.issue_summary }}
          issue_description: ${{ github.event.inputs.issue_description }}
          issue_priority: ${{ github.event.inputs.issue_priority }}
          
      - name: ✅ Workflow Complete
        run: echo "✅ Jira issue created successfully!"

Step 3: Execute

1. Navigate to Actions tab in your repository
2. Select Create Jira Issue workflow
3. Click Run workflow
4. Fill in the required parameters
5. Watch your Jira issue being created automatically!

🛠️ Configuration Reference

Required Inputs

Input	Description	Example
jira_server	Full Jira server URL	https://company.atlassian.net
jira_username	Jira username or email	john.doe@company.com
jira_api_token	Jira API token	ATATT3xFfGF0...
project_key	Jira project identifier	PROJ, DEV, BUG
issue_type	Type of issue to create	Task, Bug, Story
issue_summary	Brief issue title	Fix login validation bug
issue_description	Detailed issue description	The login form accepts...
issue_priority	Issue priority level	High, Medium, Low

Optional Inputs

Input	Description	Example	Default
parent_issue_key	Parent for Sub-task creation	PROJ-123	-
assignee	Jira username to assign	john.doe	Unassigned
issue_labels	Comma-separated labels	bug,frontend,critical	-
attachment_paths	File paths to attach	./logs/error.log,./screenshots/bug.png	-

📖 Advanced Usage

Creating Sub-tasks

- name: Create Sub-task
  uses: solarekm/jira-issue@v2
  with:
    jira_server: ${{ secrets.JIRA_SERVER }}
    jira_username: ${{ secrets.JIRA_USERNAME }}
    jira_api_token: ${{ secrets.JIRA_API_TOKEN }}
    project_key: "PROJ"
    issue_type: "Sub-task"
    parent_issue_key: "PROJ-123"  # Required for Sub-tasks
    issue_summary: "Implement user authentication"
    issue_description: "Add OAuth 2.0 authentication flow"
    issue_priority: "High"
    assignee: "developer.name"

Adding Attachments

- name: Create Issue with Attachments
  uses: solarekm/jira-issue@v2
  with:
    # ... other parameters ...
    attachment_paths: "./logs/error.log,./screenshots/issue.png,./docs/specification.pdf"

Batch Issue Creation

name: Create Multiple Issues

on:
  workflow_dispatch:
    inputs:
      issues:
        description: "JSON array of issues to create"
        required: true

jobs:
  create_issues:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        issue: ${{ fromJson(github.event.inputs.issues) }}
    steps:
      - name: Create Issue
        uses: solarekm/jira-issue@v2
        with:
          jira_server: ${{ secrets.JIRA_SERVER }}
          jira_username: ${{ secrets.JIRA_USERNAME }}
          jira_api_token: ${{ secrets.JIRA_API_TOKEN }}
          project_key: ${{ matrix.issue.project }}
          issue_type: ${{ matrix.issue.type }}
          issue_summary: ${{ matrix.issue.summary }}
          issue_description: ${{ matrix.issue.description }}
          issue_priority: ${{ matrix.issue.priority }}

🔧 Advanced Features

🏗️ Modular Architecture

• 🎯 Single Responsibility: Each module handles specific functionality
• 🔧 Maintainable: Clean code structure with proper separation of concerns
• 🧪 Testable: Comprehensive unit and integration tests
• 📚 Documented: Inline documentation and type hints

🔒 Security Hardening

• �️ Input Validation: Multi-layer validation with custom validators
• 🔍 Injection Protection: SQL, XSS, and command injection prevention
• � Secure Handling: Safe credential and token management
• 📊 Audit Trail: Comprehensive logging for security monitoring

🚀 Performance & Reliability

• ⚡ Optimized: Efficient API calls with retry logic
• � Resilient: Graceful error handling and recovery
• 📈 Scalable: Designed for high-volume usage
• 🎯 Precise: Accurate error categorization and reporting

🧪 Quality Assurance

• ✅ Test Coverage: 95%+ code coverage with comprehensive tests
• 🔍 Static Analysis: Automated code quality checks
• � Security Scanning: Automated vulnerability detection
• 📊 Performance Testing: Load and stress testing capabilities

🚨 Error Handling & Debugging

The action provides comprehensive error handling with detailed diagnostics:

HTTP Status Codes

Code	Category	Meaning	Resolution
400	Client Error	Bad Request - Invalid parameters	Check input validation and format
401	Auth Error	Unauthorized - Invalid credentials	Verify username and API token
403	Auth Error	Forbidden - Insufficient permissions	Check Jira project permissions
404	Resource Error	Not Found - Invalid resource	Verify server URL, project key, or parent issue
429	Rate Limit	Too Many Requests	Wait and retry, implement backoff
500	Server Error	Internal Server Error	Contact Jira administrator
503	Server Error	Service Unavailable	Temporary issue, retry later

Custom Exception Types

• ValidationError: Input validation failures with detailed field information
• JiraConnectionError: Network and authentication issues
• JiraOperationError: Jira-specific operation failures
• SecurityError: Security validation failures and injection attempts

Debug Mode

Enable debug logging by setting the JIRA_DEBUG environment variable:

- name: Create Jira Issue (Debug Mode)
  uses: solarekm/jira-issue@v2
  env:
    JIRA_DEBUG: "true"
  with:
    # ... your parameters ...

Common Issues & Solutions

Issue: ValidationError: Invalid project key format

• Solution: Ensure project key contains only uppercase letters and numbers

Issue: JiraConnectionError: Unable to connect to Jira server

• Solution: Verify server URL format (must include https://)

Issue: SecurityError: Potentially malicious input detected

• Solution: Review input content for special characters or script tags

⚠️ Security Limitations & Best Practices

🔒 Input Content Restrictions

For security reasons, the action implements strict validation that may reject some legitimate content:

Issue Descriptions & Summaries

# ❌ AVOID: Characters that trigger security detection
description: "Process failed with error code (123) - see output"
summary: "Fix bug in calculate() function"

# ✅ RECOMMENDED: Use alternative notation
description: "Process failed with error code 123 - see output"  
summary: "Fix bug in calculate function"

Restricted Characters in Text Fields:

• Parentheses () - Detected as potential shell injection
• Semicolons ; - Command separator detection
• Pipe characters | - Command chaining detection
• Backticks ` - Command execution detection
• Dollar signs with parentheses $() - Variable expansion detection

Workarounds:

• Use square brackets [] instead of parentheses
• Use "and" instead of & or ;
• Use "or" instead of |
• Avoid shell-like syntax in descriptions

Attachment File Paths

# ❌ REJECTED: Absolute paths and directory traversal
attachment_paths: "/tmp/report.txt,../config/settings.json"

# ✅ ACCEPTED: Relative paths from workflow root
attachment_paths: "reports/output.txt,logs/debug.log"

Path Restrictions:

• No absolute paths starting with /
• No directory traversal patterns ../
• Files must exist and be readable
• Maximum file size: 10MB per file

🛡️ Security Design Principles

1. Zero-Trust Validation: All inputs are treated as potentially malicious
2. Defense in Depth: Multiple layers of security validation
3. Fail-Safe Defaults: Reject ambiguous content rather than risk exposure
4. Principle of Least Privilege: Minimal required permissions only

🎯 Testing Considerations

When writing tests that interact with these security features:

• Use simple, non-shell-like syntax in test content
• Test with relative file paths only
• Expect validation errors for security-sensitive patterns
• Design test cases around the security constraints

🤝 Contributing

We welcome contributions! This project follows modern development practices with comprehensive testing and documentation.

Quick Start for Contributors

1. Fork & Clone: Fork the repository and clone your fork
2. Environment Setup: Install Python 3.11+ and dependencies
3. Run Tests: Execute the test suite to ensure everything works
4. Make Changes: Follow our coding standards and security guidelines
5. Test Changes: Ensure all tests pass and add new tests for new features
6. Submit PR: Create a pull request with a clear description

Development Environment

# Clone your fork
git clone https://github.com/YOUR_USERNAME/jira-issue.git
cd jira-issue

# Install dependencies
pip install -r requirements.txt
pip install -r tests/requirements-test.txt

# Run tests
python -m pytest tests/ --cov=src --cov-report=html

# Run security checks
bandit -r src/
safety check -r requirements.txt

Code Quality Standards

• 🐍 Python 3.11+: Modern Python with type hints
• 🧪 Test Coverage: Maintain 95%+ test coverage
• 🔒 Security: Follow security best practices
• 📚 Documentation: Document all public APIs
• 🎨 Code Style: Follow PEP 8 and use black formatter

For detailed contributor guidelines, see CONTRIBUTING.md.

Architecture Overview

The action follows a modular architecture:

• src/main.py: Main orchestration and entry point
• src/jira_client.py: Jira API client with retry logic
• src/validators.py: Input validation and security checks
• src/exceptions.py: Custom exception handling
• src/utils.py: Utility functions and helpers

For detailed development information, see docs/development.md.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Atlassian team for the excellent Jira REST API
• GitHub team for the powerful Actions platform
• Python Jira library maintainers
• Open source community for continuous improvements

📞 Support & Resources

🆘 Getting Help

• 📋 Issues: GitHub Issues - Bug reports and feature requests
• 💬 Discussions: GitHub Discussions - Questions and community support
• 🔒 Security: Security Policy - Vulnerability reporting process
• 📚 Contributing: Contributor Guide - Development guidelines

📖 Documentation

• 🏠 Main Documentation: This README for usage and examples
• 📚 Examples & Use Cases: docs/examples.md - Practical examples and integration patterns
• 🚨 Troubleshooting Guide: docs/troubleshooting.md - Common issues and solutions
• 🔧 Development Guide: docs/development.md - Architecture and development setup
• 🔒 Security Constraints: docs/SECURITY_CONSTRAINTS.md - Security validation guidelines
• 📋 API Reference: Jira REST API Documentation
• ⚙️ GitHub Actions: GitHub Actions Documentation

🔗 Related Resources

• 🐍 Jira Python Library: PyPI Package - Core Jira API client
• 🛒 GitHub Marketplace: Actions Marketplace - Discover more actions
• 🏢 Atlassian Developer: Developer Documentation - Official Atlassian resources
• 🔐 Security Best Practices: GitHub Security Advisories

📊 Project Status

• 🔄 Active Maintenance: Regularly updated and maintained
• 🧪 CI/CD Pipeline: All workflows passing (Quality Assurance ✅)
• 🔒 Security Hardened: CodeQL + Dependabot enabled with zero-tolerance policy
• 📈 Production Ready: Enterprise-grade reliability and security
• 🎯 Test Coverage: 80%+ comprehensive test suite with ongoing improvements