GitHub Issues Sync Action

Overview

This project is a GitHub Action that provides bidirectional synchronization between GitHub issues and local markdown files. It allows teams to manage GitHub issues locally using markdown files with YAML frontmatter, enabling version control of issues and integration with local development workflows.

System Architecture

Core Architecture

• Node.js Application: Built on Node.js 20 runtime
• GitHub Actions Framework: Uses @actions/core and @actions/github for GitHub integration
• File-based Storage: Issues stored as markdown files with YAML frontmatter
• Bidirectional Sync: Supports pull (GitHub → Local), push (Local → GitHub), or both directions

Key Design Decisions

1. Markdown + YAML Format: Chosen for human readability and version control compatibility
2. Directory Organization: Issues organized into open/ and closed/ subdirectories for clarity
3. Conflict Resolution: Multiple strategies (fail, create-files, overwrite) to handle sync conflicts
4. Comprehensive Metadata: Preserves all GitHub issue metadata including labels, assignees, milestones

Key Components

Entry Point (src/index.js)

• Main orchestrator that handles input validation and sync direction routing
• Manages error handling and output reporting
• Coordinates between pull and push sync operations

Sync Operations

• Pull Sync (src/sync/pull.js): Downloads issues from GitHub to local markdown files
• Push Sync (src/sync/push.js): Uploads local markdown files to GitHub as issues
• Conflict Resolver (src/sync/conflict-resolver.js): Handles conflicts between local and remote versions

Parsers

• GitHub Parser (src/parsers/github-parser.js): Converts GitHub API responses to markdown format
• Markdown Parser (src/parsers/markdown-parser.js): Converts markdown files to GitHub API format

Utilities

• File Utils (src/utils/file-utils.js): File system operations and directory management
• GitHub API (src/utils/github-api.js): GitHub API client initialization
• Logger (src/utils/logger.js): Centralized logging with debug mode support
• Validation (src/utils/validation.js): Input validation and security checks

Data Flow

Pull Sync Flow

1. Fetch all issues from GitHub repository using REST API
2. Parse each issue into markdown format with YAML frontmatter
3. Check for existing local files and detect conflicts
4. Apply conflict resolution strategy (fail, create conflict files, or overwrite)
5. Write issues to organized directory structure (open/ or closed/)

Push Sync Flow

1. Scan local directories for markdown issue files
2. Parse markdown files to extract issue data and metadata
3. Check if issue exists on GitHub (via github_id in frontmatter)
4. Create new issues or update existing ones via GitHub API
5. Update local files with GitHub-generated metadata

File Structure

.github/issues/
├── open/
│   ├── 1-issue-title.md
│   └── 2-another-issue.md
└── closed/
    └── 3-resolved-issue.md

External Dependencies

GitHub APIs

• GitHub REST API: Primary interface for issue management
• GitHub Actions Framework: Runtime environment and utilities
• Octokit: GitHub API client with pagination support

Node.js Packages

• @actions/core: GitHub Actions toolkit for inputs/outputs
• @actions/github: GitHub context and API access
• front-matter: YAML frontmatter parsing
• fs-extra: Enhanced file system operations
• js-yaml: YAML serialization/deserialization

Authentication

• Uses GitHub token (typically ${{ secrets.GITHUB_TOKEN }}) for API access
• Requires repository read/write permissions for issues

Deployment Strategy

GitHub Actions Deployment

• Distributed as a composite GitHub Action
• Uses Node.js 20 runtime environment
• Can be triggered via schedule, workflow dispatch, or repository events
• Runs in GitHub-hosted runners (ubuntu-latest recommended)

Configuration Options

• Sync Direction: pull, push, or both
• Issues Path: Configurable directory for issue storage
• Conflict Strategy: Multiple approaches for handling conflicts
• Debug Mode: Enhanced logging for troubleshooting

Security Considerations

• Path traversal protection in validation layer
• Token-based authentication with minimal required permissions
• Input sanitization for all user-provided values

Recent Changes

• June 26, 2025: Completed full GitHub Issues Sync Action implementation
  • All core synchronization functionality working
  • Bidirectional sync (pull from GitHub, push to GitHub)
  • Comprehensive conflict resolution system
  • Complete metadata preservation (labels, assignees, milestones, comments)
  • Organized file structure with open/closed directories
  • Full validation and error handling
  • Debug logging support
  • Created demo files and comprehensive documentation

Demo Files Created

• .github/issues/open/1-fix-login-validation-bug.md - Sample new issue
• .github/issues/closed/42-update-api-documentation.md - Sample synced issue
• .github/workflows/sync-issues.yml - Example workflow configuration
• demo-setup.js - Demonstration script showing functionality

Changelog

• June 26, 2025: Initial setup and complete implementation
• June 26, 2025: Added comprehensive documentation and demo

User Preferences

Preferred communication style: Simple, everyday language.