github_pulse/SETUP.md

MicrosoftDocFlow Tool - Setup Guide

Overview

This tool automates the process of converting Azure DevOps work items into GitHub pull requests with AI assistance. It fetches work items, processes documentation changes, and creates pull requests with proper diffs.

Quick Start

Prerequisites

• Python 3.8+ installed on your system
• Git installed and configured
• Azure DevOps account with work items
• GitHub account with repository access
• AI Provider account (optional, for enhanced processing)

Installation

1. Clone/Download the Repository

   git clone https://github.com/yourusername/github_automation.git
   cd github_automation
   

2. Create Virtual Environment (Recommended)

   # Create virtual environment
   python -m venv venv
   
   # Activate virtual environment
   # On Windows:
   venv\Scripts\activate
   
   # On macOS/Linux:
   source venv/bin/activate
   

   To deactivate the environment when done:

   deactivate
   

3. Install Dependencies

   pip install -r application/requirements.txt
   

4. Run the Application

   python application/app.py
   

Virtual Environment Management

Activating the environment (when returning to the project):

• Windows: venv\Scripts\activate
• macOS/Linux: source venv/bin/activate

Deactivating the environment (when done working):

deactivate

Why use a virtual environment?

• Isolation: Keeps project dependencies separate from system Python
• Clean installs: Prevents conflicts with other Python projects
• Reproducible: Ensures consistent dependency versions
• Safe updates: Won't affect other projects when updating packages

Project Structure

The project is organized as follows:

github_automation/
├── application/              # Main application 
│   ├── app.py               # Application entry point
│   ├── requirements.txt     # Python dependencies
│   └── app_components/      # Application modules
│       ├── ai_manager.py           # AI provider 
│       ├── azure_devops_api.py     # Azure DevOps API 
│       ├── cache_manager.py        # Work item caching
│       ├── config_manager.py       # Configuration 
│       ├── dataverse_api.py        # Dataverse API 
│       ├── github_api.py           # GitHub API client
│       ├── main_gui.py             # Main GUI interface
│       ├── settings_dialog.py      # Settings dialog
│       ├── utils.py                # Utility functions
│       └── work_item_processor.py  # Work item 
├── media/                   # Images and assets
├── README.md               # Project overview
├── SETUP.md                # This setup guide
└── LICENSE                 # License information

Configuration

First-Time Setup

1. Launch the application and click "Settings" button
2. Configure required fields in the Settings dialog:

Azure DevOps Configuration (Required)

• Query URL: Your Azure DevOps query URL
  • Example: https://dev.azure.com/yourorg/project/_queries/query/12345678-1234-1234-1234-123456789abc/
  • Get this from Azure DevOps by creating/opening a query and copying the URL
• Personal Access Token: Azure DevOps PAT with work item read permissions
  • Create at: https://dev.azure.com/yourorg/_usersSettings/tokens
  • Required scopes: Work Items (Read/Write)

GitHub Configuration (Required)

• Personal Access Token: GitHub PAT for repository access
  • Create at: https://github.com/settings/tokens
  • Required scopes: repo, workflow
• Target Repository: Format as owner/repository
  • Example: microsoft/fabric-docs
• Forked Repository: Your fork of the target repository
  • Example: yourusername/fabric-docs
• Local Repo Path: Directory where repositories will be/are cloned
  • Example: C:\Users\yourname\repos\

AI Provider Configuration (Optional)

• Provider: Choose from:
  • none - GitHub Copilot via a automatic comment on the PR
  • claude - Anthropic Claude API
  • chatgpt - OpenAI ChatGPT API
  • github-copilot - GitHub Models API
• API Keys: Provide keys based on your chosen provider
  • GitHub Token: Auto-defaults to GitHub PAT if left empty

Configuration Tips

Start Simple: Configure only Azure DevOps and GitHub initially
Test Connection: Use "Test Connection" button to verify settings
Cache Benefits: Work items are cached for faster subsequent loads
AI Enhancement: Add AI provider later for automated text processing

Usage Guide

Basic Workflow

1. Load Work Items

   • Click "Fetch Work Items" to load work items from your query
   • Items are displayed in the "All Work Items" tab
   • Cached items load automatically on subsequent launches

2. Select Work Item

   • Navigate to "All Work Items" tab
   • Double-click any work item to select it as current
   • OR click "Set as Current Item" button
   • Selected item appears in "Current Work Item" tab

3. Review Work Item Details

   • Work Item ID: Click to open in Azure DevOps
   • Nature of Request: Description of required changes
   • Document URL: Target documentation URL
   • Text to Change: Current text that needs modification
   • Proposed New Text: Replacement text (editable)

4. Process Changes

   • With AI: If AI provider is configured and the AI provider is not none, click "Create PR" and the selected AI will be used
   • Manual: Click "Create PR" or "Create Issue" for manual processing / GitHub Copilot comment
   • Dry Run: Enable for testing without actual changes (Located in settings)

Advanced Features

Work Item Navigation

• Next/Previous: Navigate through multiple work items
• Edit Mode: Click "Edit" to modify proposed text

Git Diff Viewer

• View file changes in the "Git Diff" tab
• Shows before/after comparison
• Automatic diff generation from repository changes

Processing Log

• Real-time activity logging in "Processing Log" tab
• Track API calls, file operations, and errors
• Detailed workflow visibility

Advanced Configuration

AI Provider Setup

Claude (Anthropic)

1. Get API key from console.anthropic.com
2. Set provider to claude
3. Enter API key in settings
4. Cost: ~$0.01-0.05 per work item

ChatGPT (OpenAI)

1. Get API key from platform.openai.com/api-keys
2. Set provider to chatgpt
3. Enter API key in settings
4. Cost: ~$0.01-0.05 per work item

GitHub Copilot

1. Ensure GitHub account has Copilot access
2. Set provider to github-copilot
3. GitHub Token auto-defaults to GitHub PAT
4. Uses GitHub Models API

Repository Management

Local Repository Setup

• Automatic Cloning: Repositories are cloned automatically to Local Repo Path if AI provider is used
• Branch Management: Creates feature branches for each work item
• Sync Handling: Keeps repositories updated with upstream changes

Forked Repository Workflow

1. Fork the target repository to your GitHub account
2. Configure both target and forked repositories in settings
3. Automatic: Tool manages branch creation and PR submission

Custom Instructions

Add custom AI instructions in settings to guide processing:

Focus on technical accuracy and clear documentation.
Ensure all code examples are properly formatted.
Include relevant cross-references to related topics.

🛠️ Troubleshooting

Common Issues

"No work items found"

• Verify Azure DevOps query URL is correct
• Check PAT has work item read permissions
• Ensure query returns results in Azure DevOps

"Repository not found"

• Verify GitHub repository name format (owner/repo)
• Check GitHub PAT has repository access
• Ensure repository exists and is accessible

"AI processing failed"

• Verify API key is correct and has credits
• Check internet connection
• Review processing log for specific errors

"Git operations failed"

• Ensure Git is installed and configured
• Check Local Repo Path exists and is writable
• Verify GitHub authentication is working

Performance Tips

Use Cache: Let items load from cache for faster startup
Dry Run: Test changes before committing
Batch Processing: Process multiple items in sequence
Monitor Logs: Watch processing log for issues

Security Best Practices

Token Security

• Never commit .env file to version control
• Rotate tokens regularly (90 days recommended)
• Minimum permissions: Use least privilege principle
• Secure storage: Store tokens in secure password manager

Repository Access

• Fork workflow: Use personal forks for changes
• Branch isolation: Each work item gets separate branch
• Review process: All changes go through pull requests

Support

Getting Help

1. Check logs in Processing Log tab for detailed errors
2. Test connections using Settings dialog test button
3. Review configuration for missing or incorrect values
4. Consult documentation for API-specific issues

Common Resources

• Azure DevOps PAT Documentation
• GitHub PAT Documentation
• Git Configuration Guide