github_pulse/SETUP.md

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
• libmpv installed on your system (Linux)

Installation

1. Clone/Download the Repository

   git clone https://github.com/TySP-Dev/github_pulse.git
   cd github_pulse/src
   

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
   

3. Install Dependencies

   # For all production dependencies
   pip install -r requirements/requirements.txt
   

   # For dev dependencies
   pip install -r requirements/requirements-dev.txt
   

   # For ai dependencies
   pip install -r requirements/requirements-ai.txt
   

   # For base dependencies
   pip install -r requirements/requirements-base.txt
   

4. Run the Application

   python main.py
   

Note

It is highly recommended to use a virtual environment to manage dependencies and avoid conflicts with other Python projects on your system. Ensure you activate the virtual environment each time you work on or start this application.

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_pulse/
├── src/             # Main application directory
│   ├── main.py               # Application entry point
│   ├── requirements.txt     # Python dependencies
│   ├── assets/               # Images for build
│   │   ├── icon.png         # Application icon
│   │   └── splash_android.png # Splash screen image
│   ├── requirements/  
│   │   ├── requirements-dev.txt  # Development dependencies
│   │   ├── requirements-ai.txt  # AI dependencies
│   │   ├── requirements.txt  # Production dependencies
│   │   └── requirements-base.txt  # Base dependencies
│   └── app_components/      # Application modules
│       ├── assets/          # Images and assets
│       │   ├── flow-diagram.png              # Workflow diagram              
│       │   ├── github_pulse_img.png          # GitHub Pulse image
│       │   ├── pulse_logo_gray_no_bkg.png  # GitHub Pulse logo
│       │   ├── pulse_logo_white_no_bkg_github.png          # Pulse logo
│       │   ├── pulse_logo_white_no_bkg.png               # Pulse logo with background
│       │   └── pulse_logo_white_w_black_bkg.png      # GitHub Pulse logo with background
│       ├── __init__.py          # Package initializer
│       ├── 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
│       ├── processing_log_dialog.py  # Processing log dialog
│       ├── settings_dialog.py      # Settings dialog
│       ├── settings_manager.py     # Settings management
│       ├── utils.py                # Utility functions
│       └── workflow.py             # Workflow processing
├── assets/                   # Images and assets
├── README.md               # Readme file
├── SETUP.md                # This file
└── 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
  • ollama - Ollama Local Models
• Ollama Model: Select model based on local availability
• Ollama API Endpoint: URL for Ollama AI server
• 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 Configuration File: Settings are saved in config.json for persistence

Security Best Practices

Token Security

• Use PATs instead of passwords
• Rotate tokens regularly (90 days recommended)
• Minimum permissions: Use least privilege principle
• Secure storage: Store tokens in secure password manager
• Avoid hardcoding: Never hardcode tokens in source code
• Secret management: This project uses keyring for secure storage

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
• Git Configuration Guide