b-tsammmons
0f41a3e750
- 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.
160 lines
4.5 KiB
Markdown
160 lines
4.5 KiB
Markdown
# GitHub Pulse - Setup Guide
|
|
|
|
## Overview
|
|
|
|
A Python-based GUI application for GitHub automation workflows.
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- **Python 3.8+** installed on your system
|
|
- **Git** installed and configured
|
|
- **GitHub** account with repository access
|
|
|
|
### Installation
|
|
|
|
1. **Clone/Download the Repository**
|
|
|
|
```bash
|
|
git clone https://github.com/TySP-Dev/github_automation.git
|
|
cd github_automation/application
|
|
```
|
|
|
|
2. **Create Virtual Environment** (Recommended)
|
|
|
|
```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:
|
|
|
|
```bash
|
|
deactivate
|
|
```
|
|
|
|
3. **Install Dependencies**
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
4. **Run the Application**
|
|
|
|
```bash
|
|
python 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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
github_automation/
|
|
├── application/ # Main application directory
|
|
│ ├── app.py # Application entry point
|
|
│ ├── requirements.txt # Python dependencies
|
|
│ └── app_components/ # Application modules
|
|
│ ├── 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
|
|
├── 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
|
|
|
|
#### 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/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` - No AI assistance
|
|
- `claude` - Anthropic Claude API
|
|
- `chatgpt` - OpenAI ChatGPT API
|
|
- `github-copilot` - GitHub Models API
|
|
- **API Keys**: Provide keys based on your chosen provider
|
|
|
|
### Configuration Tips
|
|
|
|
**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
|
|
|
|
### 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 task 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
|
|
|
|
### Common Resources
|
|
|
|
- [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)
|