Skip to content

USER_GUIDE.md

Latest commit

 

History

History
152 lines (111 loc) · 5.05 KB

USER_GUIDE.md

File metadata and controls

152 lines (111 loc) · 5.05 KB

GitHub Branch Analyzer - User Guide

This guide will walk you through the process of setting up and using the GitHub Branch Analyzer to visualize branch comparisons from your private GitHub repositories.

Overview

The GitHub Branch Analyzer allows you to:

  1. Connect to your private GitHub repositories using a Personal Access Token
  2. Extract information about branches merged via pull requests
  3. Compare branches (typically "main" and "release") to see which feature branches were merged where
  4. Visualize the comparison with an interactive web interface

Prerequisites

  • A GitHub account with access to the private repository you want to analyze
  • A Personal Access Token (PAT) with appropriate permissions
  • Basic familiarity with command line operations

Step 1: Set Up GitHub API Access

  1. Create a Personal Access Token (PAT):
    • Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
    • Click "Generate new token"
    • Give it a name like "Branch Comparison Tool"
    • Set the expiration as needed
    • Select the specific repository you want to analyze
    • Under "Repository permissions", grant at least "Read access" to:
      • Contents
      • Pull requests
      • Metadata
    • Click "Generate token"
    • IMPORTANT: Copy the generated token immediately and store it securely. You won't be able to see it again!

Step 2: Configure the Branch Analyzer

  1. Run the configuration script:

    cd /path/to/github-branch-analyzer
./configure.sh

  2. Enter the requested information:

    • GitHub Personal Access Token (the one you created in Step 1)
    • Repository name in the format "owner/repo-name" (e.g., "myusername/myproject")
    • Main branch name (default is "main")
    • Release branch name (default is "release")

Step 3: Run the Branch Analysis

  1. Execute the analysis script:

    cd /path/to/github-branch-analyzer
./run.sh

  2. Review the analysis output:

    • The script will display a summary of the analysis results
    • The complete results are saved to analyzed_branch_data.json

Step 4: View the Visualization

You can view the branch comparison visualization in two ways:

Option 1: Use the Deployed Website

Visit the permanently deployed visualization website at: https://jmocizgq.manus.space

To use your own data with this website:

  1. Copy your analyzed_branch_data.json file to the same directory as the website
  2. Refresh the page to see your data

Option 2: Run the Visualization Locally

  1. Copy the analysis results to the website directory:

    cp /path/to/github-branch-analyzer/analyzed_branch_data.json /path/to/git-branch-comparison-website/

  2. Start a local web server:

    cd /path/to/git-branch-comparison-website
python -m http.server 8000

  3. Open the visualization in your browser:

    • Navigate to http://localhost:8000 in your web browser

Understanding the Visualization

The visualization shows:

  • Blue Circle: Branches merged into the main branch
  • Orange Circle: Branches merged into the release branch
  • Overlap: Branches that appear in both main and release

Interactive features:

  • Hover over branches to see details
  • Click on a branch to see more information
  • Use the search box to find specific branches
  • Use the checkboxes to filter which branches are displayed

Automating the Process

To automate the branch analysis, you can:

  1. Create a cron job to run the analysis periodically:

    # Example: Run analysis daily at 2 AM
0 2 * * * cd /path/to/github-branch-analyzer && ./run.sh

  2. Set up a GitHub Action to run the analysis on push events or on a schedule

Troubleshooting

Common Issues:

  1. Authentication Errors:

    • Ensure your Personal Access Token has the correct permissions
    • Check that the token hasn't expired
    • Verify you're using the correct token

  2. Repository Not Found:

    • Confirm the repository name is in the format "owner/repo-name"
    • Verify that your GitHub account has access to the repository

  3. No Data Displayed:

    • Check that the analysis completed successfully
    • Verify that the JSON file was copied to the correct location
    • Ensure the JSON file has the expected format

  4. Visualization Not Loading:

    • Check your browser console for JavaScript errors
    • Ensure all files (HTML, CSS, JS) are in the same directory
    • Try using a different browser

Getting Help

If you encounter issues not covered in this guide, please:

  1. Check the GitHub repository for updates or known issues
  2. Contact the developer with specific error messages and steps to reproduce the problem

Security Considerations

  • Your GitHub Personal Access Token provides access to your repositories. Keep it secure!
  • The token is stored in the .env file with restricted permissions (readable only by you)
  • Consider using a token with the minimum necessary permissions and a short expiration time
  • Regularly rotate your tokens for enhanced security

sebas correa