TySS-Dev/github_pulse
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor GitHub automation tool:

Browse Source 
- Updated WorkItemFieldExtractor to be more generic and removed Azure DevOps specific references.
- Removed the EnhancedContentBuilders class as it was specific to Azure DevOps.
- Deleted work_item_processor.py as it was no longer needed.
- Introduced workflow.py to manage GitHub workflow items (issues and pull requests) with improved structure and functionality.
- Enhanced logging and error handling across the new workflow management system.
This commit is contained in:
b-tsammmons
2025-11-11 22:46:02 -10:00
parent d6da461d10
commit 0f41a3e750
15 changed files with 2003 additions and 1446 deletions
Download Patch File Download Diff File Expand all files Collapse all files
SETUP.md
+24 -172
View File
@@ -1,8 +1,8 @@
# MicrosoftDocFlow Tool - Setup Guide
# GitHub Pulse - 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.
A Python-based GUI application for GitHub automation workflows.
## Quick Start
@@ -10,9 +10,7 @@ This tool automates the process of converting Azure DevOps work items into GitHu
- **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
@@ -20,7 +18,7 @@ This tool automates the process of converting Azure DevOps work items into GitHu
```bash
git clone https://github.com/TySP-Dev/github_automation.git
cd github_automation\application
cd github_automation/application
```
2. **Create Virtual Environment** (Recommended)
@@ -28,20 +26,20 @@ This tool automates the process of converting Azure DevOps work items into GitHu
```bash
# 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:
To deactivate the environment when done:
```bash
deactivate
```
```bash
deactivate
```
3. **Install Dependencies**
@@ -81,20 +79,17 @@ The project is organized as follows:
```text
github_automation/
├── application/ # Main application
├── application/ # Main application directory
│ ├── 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
│ ├── ai_manager.py # AI provider integration
│ ├── cache_manager.py # Caching functionality
│ ├── config_manager.py # Configuration management
│ ├── 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
│ └── utils.py # Utility functions
├── media/ # Images and assets
├── README.md # Project overview
├── SETUP.md # This setup guide
@@ -106,16 +101,7 @@ github_automation/
### 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)
2. **Configure required fields** in the Settings dialog
#### GitHub Configuration (Required)
@@ -123,158 +109,26 @@ github_automation/
- 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`
- Example: `microsoft/example-repo`
- **Forked Repository**: Your fork of the target repository (if applicable)
- Example: `yourusername/example-repo`
- **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
- `none` - No AI assistance
- `claude` - Anthropic Claude API
- `chatgpt` - OpenAI ChatGPT 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](https://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](https://platform.openai.com/api-keys)
1. Set provider to `chatgpt`
1. Enter API key in settings
1. 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:
```AI Prompt
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
**Start Simple**: Configure only GitHub initially
**Test Connection**: Use "Test Connection" button to verify settings
**AI Enhancement**: Add AI provider later for automated processing
## Security Best Practices
@@ -288,7 +142,7 @@ Include relevant cross-references to related topics.
### Repository Access
- **Fork workflow**: Use personal forks for changes
- **Branch isolation**: Each work item gets separate branch
- **Branch isolation**: Each task gets separate branch
- **Review process**: All changes go through pull requests
## Support
@@ -298,10 +152,8 @@ Include relevant cross-references to related topics.
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](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate)
- [GitHub PAT Documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
- [Git Configuration Guide](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup)