gitflow-analytics 3.13.5__tar.gz → 3.13.7__tar.gz

{gitflow_analytics-3.13.5 → gitflow_analytics-3.13.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitflow-analytics
-Version: 3.13.5
+Version: 3.13.7
 Summary: Analyze Git repositories for developer productivity insights
 Author-email: Bob Matyas <bobmatnyc@gmail.com>
 License: MIT

gitflow_analytics-3.13.7/docs/research/csv-generation-narrative-bug-20251222.md

@@ -0,0 +1,412 @@
+# Bug Analysis: CSV Generation Disabled but Narrative Report Still Tries to Read CSV
+
+**Date**: 2025-12-22
+**Analyst**: Research Agent
+**Priority**: High
+**Type**: Logic Error / Missing Conditional Check
+
+## Executive Summary
+
+When qualitative analysis runs with "CSV generation disabled", the code still unconditionally tries to read `qualitative_insights_20251222.csv`, causing a `FileNotFoundError`. The root cause is that CSV files are **always generated** regardless of the `generate_csv` flag, but the narrative report generation assumes these CSVs exist and attempts to read them without checking if CSV generation was enabled.
+
+## Bug Details
+
+### Symptom
+```
+Error: FileNotFoundError: [Errno 2] No such file or directory: 'qualitative_insights_20251222.csv'
+```
+
+This occurs when:
+1. User runs analysis with CSV generation disabled (`--no-csv` flag or config setting)
+2. Narrative report generation is enabled (`markdown` in output formats)
+3. The code tries to load CSV files that were never written to disk
+
+### Root Cause Analysis
+
+**The Fundamental Problem**: The comment "always generate data, optionally write CSV" is misleading. The CSV files ARE written to disk unconditionally, but when `generate_csv=False`, they are deleted or not added to the reports list.
+
+#### Code Flow
+
+**Step 1: CSV Report Generation (Lines 3663-3725)**
+
+All three CSV reports follow the same flawed pattern:
+
+```python
+# Activity distribution report (always generate data, optionally write CSV)
+activity_report = output / f"activity_distribution_{datetime.now().strftime('%Y%m%d')}.csv"
+try:
+    logger.debug("Starting activity distribution report generation")
+    analytics_gen.generate_activity_distribution_report(
+        all_commits, developer_stats, activity_report
+    )
+    logger.debug("Activity distribution report completed successfully")
+    if generate_csv:  # ⚠️ Only controls whether report is LISTED, not whether it's WRITTEN
+        generated_reports.append(activity_report.name)
+        if not display:
+            click.echo(f"   ✅ Activity distribution: {activity_report}")
+```
+
+**What Actually Happens**:
+- `generate_activity_distribution_report()` is called unconditionally
+- Inside `analytics_writer.py:316-346`, the CSV is **written to disk** (line 344: `df.to_csv(output_path, index=False)`)
+- The `if generate_csv` check only controls:
+  - Whether the filename is added to `generated_reports` list
+  - Whether a success message is printed
+
+**The Same Pattern for All Three CSVs**:
+1. **activity_report** (lines 3663-3685)
+2. **focus_report** (lines 3687-3709)
+3. **insights_report** (lines 3711-3725)
+
+All three reports:
+- Define the CSV path
+- Call the generator function (which writes CSV to disk)
+- Only conditionally add to `generated_reports` list if `generate_csv=True`
+
+**Step 2: Narrative Report Generation (Lines 3911-4039)**
+
+The narrative report generation **unconditionally reads all three CSVs**:
+
+```python
+# Generate markdown reports if enabled
+if "markdown" in cfg.output.formats:
+    # Calculate date range for consistent filename formatting across all markdown reports
+    date_range = f"{start_date.strftime('%Y%m%d')}_{end_date.strftime('%Y%m%d')}"
+
+    try:
+        logger.debug("Starting narrative report generation")
+        narrative_gen = NarrativeReportGenerator()
+
+        # Lazy import pandas - only needed for CSV reading in narrative generation
+        import pandas as pd
+
+        # Load activity distribution data
+        logger.debug("Loading activity distribution data")
+        activity_df = pd.read_csv(activity_report)  # ⚠️ ASSUMES CSV EXISTS
+        activity_data = cast(list[dict[str, Any]], activity_df.to_dict("records"))
+
+        # Load focus data
+        logger.debug("Loading focus data")
+        focus_df = pd.read_csv(focus_report)  # ⚠️ ASSUMES CSV EXISTS
+        focus_data = cast(list[dict[str, Any]], focus_df.to_dict("records"))
+
+        # Load insights data
+        logger.debug("Loading insights data")
+        insights_df = pd.read_csv(insights_report)  # ⚠️ ASSUMES CSV EXISTS
+        insights_data = cast(list[dict[str, Any]], insights_df.to_dict("records"))
+```
+
+**Problem**: The narrative report generation has NO conditional check for `generate_csv`. It assumes the CSV files exist on disk.
+
+### Variables Involved
+
+| Variable | Definition Line | Purpose | Current Behavior |
+|----------|----------------|---------|------------------|
+| `generate_csv` | Function parameter | Controls whether CSVs should be generated | Only controls whether CSVs are listed in `generated_reports`, NOT whether they're written |
+| `activity_report` | Line 3664 | Path to activity CSV | Path is defined, CSV is written, but may not be listed |
+| `focus_report` | Line 3688 | Path to focus CSV | Path is defined, CSV is written, but may not be listed |
+| `insights_report` | Line 3712 | Path to insights CSV | Path is defined, CSV is written, but may not be listed |
+| `generated_reports` | List variable | Tracks which reports to display | Only includes CSVs if `generate_csv=True` |
+
+### The Contradiction
+
+**Comment Says**: "always generate data, optionally write CSV"
+
+**Reality Is**:
+- CSV is **always written** to disk (line 344 in `analytics_writer.py`)
+- The `generate_csv` flag only controls reporting/listing
+- BUT: If CSV generation is disabled in the future (e.g., by wrapping the generator call in `if generate_csv:`), the narrative report will break
+
+**Why This Works Sometimes**:
+Currently, the bug doesn't manifest because CSVs ARE always written. The bug will appear if:
+1. Someone "fixes" the CSV generation to respect the `generate_csv` flag
+2. The CSV file gets deleted between generation and narrative report
+3. File permissions prevent CSV writing but don't raise an exception
+
+## Impact Analysis
+
+### Current State
+- **Low Impact**: CSVs are always written, so narrative report succeeds
+- **Confusion**: Users see "CSV generation disabled" but CSVs are still created
+- **Technical Debt**: Misleading code comments and variable names
+
+### If CSV Generation is "Fixed"
+- **High Impact**: Narrative report will crash with FileNotFoundError
+- **User Experience**: Broken feature when CSV generation is disabled
+- **Data Loss**: No way to generate narrative reports without CSV files
+
+## Recommended Fix Approach
+
+### Option 1: Skip Narrative Report When CSV Disabled (Conservative)
+
+**Rationale**: If CSV generation is disabled, don't generate narrative report at all.
+
+**Change Location**: `cli.py` lines 3911-3039
+
+**Implementation**:
+```python
+# Generate markdown reports if enabled
+if "markdown" in cfg.output.formats and generate_csv:  # ⚠️ ADD generate_csv CHECK
+    # Calculate date range for consistent filename formatting across all markdown reports
+    date_range = f"{start_date.strftime('%Y%m%d')}_{end_date.strftime('%Y%m%d')}"
+
+    try:
+        logger.debug("Starting narrative report generation")
+        # ... rest of the code unchanged ...
+```
+
+**Pros**:
+- Minimal code change
+- Clear logic: no CSVs = no narrative report
+- No risk of file not found errors
+
+**Cons**:
+- Users lose narrative reports when CSV generation is disabled
+- Doesn't address the underlying architectural issue
+
+### Option 2: Generate In-Memory Data Without Writing CSVs (Optimal)
+
+**Rationale**: Separate data generation from CSV writing. Generate data in memory, optionally write CSVs, always pass data to narrative report.
+
+**Change Locations**:
+1. `analytics_writer.py` lines 316-346 (and similar methods)
+2. `cli.py` lines 3663-3725
+
+**Implementation**:
+
+**Step 1**: Modify report generators to return data AND optionally write CSV:
+
+```python
+def generate_qualitative_insights_report(
+    self,
+    commits: List[Dict[str, Any]],
+    developer_stats: List[Dict[str, Any]],
+    ticket_analysis: Dict[str, Any],
+    output_path: Path | None = None  # ⚠️ Make optional
+) -> tuple[pd.DataFrame, Path | None]:  # ⚠️ Return data AND path
+    """Generate qualitative insights and patterns report."""
+    # Apply exclusion filtering in Phase 2
+    commits = self._filter_excluded_authors(commits)
+    developer_stats = self._filter_excluded_authors(developer_stats)
+    insights = []
+
+    # Analyze commit patterns
+    commit_insights = self._analyze_commit_patterns(commits)
+    insights.extend(commit_insights)
+
+    # ... other analysis steps ...
+
+    # Create DataFrame
+    df = pd.DataFrame(insights)
+
+    # Write CSV only if path provided
+    written_path = None
+    if output_path is not None:
+        df.to_csv(output_path, index=False)
+        written_path = output_path
+
+    return df, written_path  # ⚠️ Return both data and path
+```
+
+**Step 2**: Update CLI to use returned data:
+
+```python
+# Qualitative insights report (always generate data, optionally write CSV)
+insights_report_path = output / f"qualitative_insights_{datetime.now().strftime('%Y%m%d')}.csv" if generate_csv else None
+try:
+    logger.debug("Starting qualitative insights report generation")
+    insights_df, insights_written_path = analytics_gen.generate_qualitative_insights_report(
+        all_commits, developer_stats, ticket_analysis, insights_report_path
+    )
+    insights_data = cast(list[dict[str, Any]], insights_df.to_dict("records"))
+    logger.debug("Qualitative insights report completed successfully")
+    if insights_written_path:
+        generated_reports.append(insights_written_path.name)
+        if not display:
+            click.echo(f"   ✅ Qualitative insights: {insights_written_path}")
+except Exception as e:
+    logger.error(f"Error in qualitative insights report generation: {e}")
+    raise
+```
+
+**Step 3**: Update narrative report to use in-memory data:
+
+```python
+# Generate markdown reports if enabled
+if "markdown" in cfg.output.formats:
+    # ... narrative generation setup ...
+
+    # Use in-memory data instead of reading CSVs
+    narrative_gen.generate_narrative_report(
+        all_commits,
+        all_prs,
+        developer_stats,
+        activity_data,  # ⚠️ Use in-memory data from Step 2
+        focus_data,     # ⚠️ Use in-memory data from Step 2
+        insights_data,  # ⚠️ Use in-memory data from Step 2
+        ticket_analysis,
+        pr_metrics,
+        narrative_report,
+        weeks,
+        aggregated_pm_data,
+        chatgpt_summary,
+        branch_health_metrics,
+        cfg.analysis.exclude_authors,
+        analysis_start_date=start_date,
+        analysis_end_date=end_date,
+    )
+```
+
+**Pros**:
+- Clean separation of concerns
+- Narrative reports work with or without CSV generation
+- No unnecessary disk I/O
+- Prevents FileNotFoundError completely
+- More testable (can test data generation without file I/O)
+
+**Cons**:
+- More extensive refactoring required
+- Need to update all three report generators
+- Need to update narrative report call
+
+### Option 3: Check File Existence Before Reading (Quick Fix)
+
+**Rationale**: Add defensive checks before reading CSVs.
+
+**Change Location**: `cli.py` lines 3920-3936
+
+**Implementation**:
+```python
+# Generate markdown reports if enabled
+if "markdown" in cfg.output.formats:
+    # Calculate date range for consistent filename formatting across all markdown reports
+    date_range = f"{start_date.strftime('%Y%m%d')}_{end_date.strftime('%Y%m%d')}"
+
+    try:
+        logger.debug("Starting narrative report generation")
+        narrative_gen = NarrativeReportGenerator()
+
+        # Lazy import pandas - only needed for CSV reading in narrative generation
+        import pandas as pd
+
+        # ⚠️ CHECK FILE EXISTENCE BEFORE READING
+        if not (activity_report.exists() and focus_report.exists() and insights_report.exists()):
+            logger.warning("CSV files not found, skipping narrative report generation")
+            if not display:
+                click.echo("   ⚠️ Narrative report skipped: CSV generation was disabled")
+            # Skip to next section
+        else:
+            # Load activity distribution data
+            logger.debug("Loading activity distribution data")
+            activity_df = pd.read_csv(activity_report)
+            # ... rest of the code unchanged ...
+```
+
+**Pros**:
+- Quick fix
+- Prevents crash
+- Minimal code change
+
+**Cons**:
+- Doesn't solve the architectural issue
+- Silent failure mode (narrative report silently skipped)
+- Still relies on CSV files existing on disk
+
+## Recommendation
+
+**Primary Recommendation**: **Option 2** (Generate In-Memory Data Without Writing CSVs)
+
+This is the most robust solution because:
+1. Eliminates the file dependency completely
+2. Improves performance (no unnecessary disk I/O)
+3. Makes the code more testable
+4. Prevents future FileNotFoundError scenarios
+5. Aligns with the original intent ("always generate data, optionally write CSV")
+
+**Fallback Recommendation**: **Option 1** (Skip Narrative Report When CSV Disabled)
+
+If Option 2 is too complex for immediate implementation:
+1. Apply Option 1 as a quick fix
+2. File a technical debt ticket for Option 2
+3. Add a warning message to users when narrative report is skipped
+
+**Not Recommended**: Option 3 (defensive file checks) - This is a band-aid that doesn't address the root cause.
+
+## Test Cases Required
+
+After implementing the fix, verify:
+
+1. **CSV Generation Enabled + Narrative Enabled**
+   - CSVs written to disk ✓
+   - Narrative report generated ✓
+   - All data consistent ✓
+
+2. **CSV Generation Disabled + Narrative Enabled**
+   - CSVs NOT written to disk ✓
+   - Narrative report generated (Option 2) or skipped with warning (Option 1) ✓
+   - No FileNotFoundError ✓
+
+3. **CSV Generation Enabled + Narrative Disabled**
+   - CSVs written to disk ✓
+   - Narrative report NOT generated ✓
+
+4. **CSV Generation Disabled + Narrative Disabled**
+   - CSVs NOT written to disk ✓
+   - Narrative report NOT generated ✓
+
+## Files Requiring Changes
+
+### Option 1 (Conservative Fix)
+- `/Users/masa/Projects/gitflow-analytics/src/gitflow_analytics/cli.py` (line 3912)
+
+### Option 2 (Optimal Fix)
+- `/Users/masa/Projects/gitflow-analytics/src/gitflow_analytics/reports/analytics_writer.py` (lines 316-346, and similar methods)
+- `/Users/masa/Projects/gitflow-analytics/src/gitflow_analytics/cli.py` (lines 3663-3725, 3911-4039)
+
+### Option 3 (Quick Fix)
+- `/Users/masa/Projects/gitflow-analytics/src/gitflow_analytics/cli.py` (lines 3920-3936)
+
+## Additional Notes
+
+### Related Code Patterns
+
+The same pattern exists for all three CSV reports:
+1. **Activity Distribution** (lines 3663-3685)
+2. **Developer Focus** (lines 3687-3709)
+3. **Qualitative Insights** (lines 3711-3725)
+
+All three need the same fix applied consistently.
+
+### Configuration Context
+
+The `generate_csv` flag comes from:
+- CLI flag: `--no-csv` or `--csv`
+- Config file: `output.formats` list (presence of "csv")
+
+The narrative report is controlled by:
+- Config file: `output.formats` list (presence of "markdown")
+
+Currently, there's no dependency between these two settings, but they should be coupled or at least documented clearly.
+
+### Performance Implications
+
+**Option 2 Benefits**:
+- Reduces disk I/O when CSV generation is disabled
+- Faster execution (no write → read cycle)
+- Lower memory pressure (no duplicate data structures)
+
+**Current Inefficiency**:
+1. Generate data in memory → write to CSV
+2. Read CSV back into memory → convert to dict
+3. Pass dict to narrative report
+
+**Option 2 Flow**:
+1. Generate data in memory
+2. Optionally write to CSV (if enabled)
+3. Pass data directly to narrative report
+
+This eliminates the write → read round-trip entirely.
+
+## Conclusion
+
+The bug is a logical error where the `generate_csv` flag is not properly checked before attempting to read CSV files in the narrative report generation. The recommended fix (Option 2) involves refactoring the report generators to separate data generation from CSV writing, allowing the narrative report to use in-memory data regardless of CSV generation settings. This provides a more robust, performant, and maintainable solution.

{gitflow_analytics-3.13.5 → gitflow_analytics-3.13.7}/pyproject.toml

@@ -96,6 +96,9 @@ target-version = "py39"
 select = ["E", "F", "UP", "B", "SIM", "I"]
 ignore = ["E501"]  # Line too long - handled by formatter
 
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["E402", "E722", "F401", "SIM102"]  # Allow test-specific patterns
+
 [tool.black]
 line-length = 100
 target-version = ['py39']

{gitflow_analytics-3.13.5 → gitflow_analytics-3.13.7}/src/gitflow_analytics/_version.py

@@ -1,4 +1,4 @@
 """Version information for gitflow-analytics."""
 
-__version__ = "3.13.5"
+__version__ = "3.13.7"
 __version_info__ = tuple(int(x) for x in __version__.split("."))

{gitflow_analytics-3.13.5 → gitflow_analytics-3.13.7}/src/gitflow_analytics/cli.py

@@ -1590,6 +1590,68 @@ def analyze(
                             total_commits += result["stats"]["total_commits"]
                             total_tickets += result["stats"]["unique_tickets"]
 
+                            # Fetch and enrich with GitHub PRs after data collection
+                            if repo_config.github_repo:
+                                try:
+                                    if display:
+                                        display.print_status(
+                                            "   📥 Fetching pull requests from GitHub...",
+                                            "info",
+                                        )
+
+                                    # Load commits that were just fetched from cache
+                                    with cache.get_session() as session:
+                                        from gitflow_analytics.models.database import CachedCommit
+
+                                        cached_commits = (
+                                            session.query(CachedCommit)
+                                            .filter(
+                                                CachedCommit.repo_path == str(repo_path),
+                                                CachedCommit.timestamp >= start_date,
+                                                CachedCommit.timestamp <= end_date,
+                                            )
+                                            .all()
+                                        )
+
+                                        # Convert to dict format for enrichment
+                                        commits_for_enrichment = []
+                                        for cached_commit in cached_commits:
+                                            commit_dict = {
+                                                "hash": cached_commit.commit_hash,
+                                                "author_name": cached_commit.author_name,
+                                                "author_email": cached_commit.author_email,
+                                                "date": cached_commit.timestamp,
+                                                "message": cached_commit.message,
+                                            }
+                                            commits_for_enrichment.append(commit_dict)
+
+                                    # Enrich with GitHub PR data
+                                    enrichment = orchestrator.enrich_repository_data(
+                                        repo_config, commits_for_enrichment, start_date
+                                    )
+
+                                    if enrichment["prs"]:
+                                        pr_count = len(enrichment["prs"])
+                                        if display:
+                                            display.print_status(
+                                                f"   ✅ Found {pr_count} pull requests",
+                                                "success",
+                                            )
+                                        else:
+                                            click.echo(f"   ✅ Found {pr_count} pull requests")
+
+                                except Exception as e:
+                                    logger.warning(
+                                        f"Failed to fetch PRs for {repo_config.github_repo}: {e}"
+                                    )
+                                    if display:
+                                        display.print_status(
+                                            f"   ⚠️  Could not fetch PRs: {e}",
+                                            "warning",
+                                        )
+                                    else:
+                                        click.echo(f"   ⚠️  Could not fetch PRs: {e}")
+
                             # Collect unique developers if available
                             if "developers" in result["stats"]:
                                 total_developers.update(result["stats"]["developers"])
@@ -2088,6 +2150,68 @@ def analyze(
                             total_commits += result["stats"]["total_commits"]
                             total_tickets += result["stats"]["unique_tickets"]
 
+                            # Fetch and enrich with GitHub PRs after data collection
+                            if repo_config.github_repo:
+                                try:
+                                    if display:
+                                        display.print_status(
+                                            "   📥 Fetching pull requests from GitHub...",
+                                            "info",
+                                        )
+
+                                    # Load commits that were just fetched from cache
+                                    with cache.get_session() as session:
+                                        from gitflow_analytics.models.database import CachedCommit
+
+                                        cached_commits = (
+                                            session.query(CachedCommit)
+                                            .filter(
+                                                CachedCommit.repo_path == str(repo_path),
+                                                CachedCommit.timestamp >= start_date,
+                                                CachedCommit.timestamp <= end_date,
+                                            )
+                                            .all()
+                                        )
+
+                                        # Convert to dict format for enrichment
+                                        commits_for_enrichment = []
+                                        for cached_commit in cached_commits:
+                                            commit_dict = {
+                                                "hash": cached_commit.commit_hash,
+                                                "author_name": cached_commit.author_name,
+                                                "author_email": cached_commit.author_email,
+                                                "date": cached_commit.timestamp,
+                                                "message": cached_commit.message,
+                                            }
+                                            commits_for_enrichment.append(commit_dict)
+
+                                    # Enrich with GitHub PR data
+                                    enrichment = orchestrator.enrich_repository_data(
+                                        repo_config, commits_for_enrichment, start_date
+                                    )
+
+                                    if enrichment["prs"]:
+                                        pr_count = len(enrichment["prs"])
+                                        if display:
+                                            display.print_status(
+                                                f"   ✅ Found {pr_count} pull requests",
+                                                "success",
+                                            )
+                                        else:
+                                            click.echo(f"   ✅ Found {pr_count} pull requests")
+
+                                except Exception as e:
+                                    logger.warning(
+                                        f"Failed to fetch PRs for {repo_config.github_repo}: {e}"
+                                    )
+                                    if display:
+                                        display.print_status(
+                                            f"   ⚠️  Could not fetch PRs: {e}",
+                                            "warning",
+                                        )
+                                    else:
+                                        click.echo(f"   ⚠️  Could not fetch PRs: {e}")
+
                             # Collect unique developers if available
                             if "developers" in result["stats"]:
                                 total_developers.update(result["stats"]["developers"])
@@ -3784,8 +3908,8 @@ def analyze(
                 traceback.print_exc()
                 raise
 
-        # Generate markdown reports if enabled
-        if "markdown" in cfg.output.formats:
+        # Generate markdown reports if enabled (requires CSV files)
+        if "markdown" in cfg.output.formats and generate_csv:
             # Calculate date range for consistent filename formatting across all markdown reports
             date_range = f"{start_date.strftime('%Y%m%d')}_{end_date.strftime('%Y%m%d')}"
 
@@ -3915,6 +4039,15 @@ def analyze(
 
                 traceback.print_exc()
                 raise
+        elif "markdown" in cfg.output.formats and not generate_csv:
+            # Narrative report requires CSV files, but CSV generation is disabled
+            logger.info(
+                "Skipping narrative report generation - CSV files required but CSV generation is disabled"
+            )
+            if not display:
+                click.echo(
+                    "   ℹ️  Narrative report skipped (requires CSV files - enable with --csv flag)"
+                )
 
         # Generate database-backed qualitative report
         if "markdown" in cfg.output.formats:

{gitflow_analytics-3.13.5 → gitflow_analytics-3.13.7}/src/gitflow_analytics/core/git_auth.py

@@ -112,6 +112,80 @@ def setup_git_credentials(token: str, username: str = "git") -> bool:
         return False
 
 
+def ensure_remote_url_has_token(repo_path: Path, token: str) -> bool:
+    """Embed GitHub token in remote URL for HTTPS authentication.
+
+    This is needed because subprocess git operations may not have access
+    to the credential helper store due to environment variable restrictions
+    (GIT_CREDENTIAL_HELPER="" and GIT_ASKPASS="/bin/echo" in git_timeout_wrapper).
+
+    Args:
+        repo_path: Path to the git repository
+        token: GitHub personal access token
+
+    Returns:
+        True if URL was updated with token, False if already has token,
+        not applicable (SSH URL), or operation failed
+    """
+    if not token:
+        logger.debug("No token provided, skipping remote URL update")
+        return False
+
+    try:
+        # Get current origin remote URL
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        current_url = result.stdout.strip()
+
+        if not current_url:
+            logger.debug(f"No origin remote found for {repo_path}")
+            return False
+
+        # Check if it's an HTTPS GitHub URL without embedded token
+        if current_url.startswith("https://github.com/"):
+            # URL format: https://github.com/org/repo.git
+            # New format: https://git:TOKEN@github.com/org/repo.git
+            new_url = current_url.replace("https://github.com/", f"https://git:{token}@github.com/")
+
+            # Update the remote URL
+            subprocess.run(
+                ["git", "remote", "set-url", "origin", new_url],
+                cwd=repo_path,
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            logger.debug(f"Updated remote URL with embedded token for {repo_path.name}")
+            return True
+
+        elif "@github.com" in current_url:
+            # Already has authentication embedded (either token or SSH)
+            logger.debug(f"Remote URL already has authentication for {repo_path.name}")
+            return False
+
+        elif current_url.startswith("git@github.com:"):
+            # SSH URL, no need to modify
+            logger.debug(f"Using SSH authentication for {repo_path.name}")
+            return False
+
+        else:
+            # Unknown URL format
+            logger.debug(f"Unknown URL format for {repo_path.name}: {current_url}")
+            return False
+
+    except subprocess.CalledProcessError as e:
+        logger.warning(f"Could not update remote URL for {repo_path.name}: {e.stderr}")
+        return False
+    except Exception as e:
+        logger.warning(f"Unexpected error updating remote URL for {repo_path.name}: {e}")
+        return False
+
+
 def preflight_git_authentication(config: dict) -> bool:
     """Run pre-flight checks for git authentication and setup credentials.