# Troubleshooting Git Remote References in the Hiring-Agent Repository

> Troubleshoot Git remote references in the hiring-agent repo. Learn how to sanitize GitHub URLs, validate tokens, and manage cache files for reliable candidate evaluation.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: how-to-guide
- Published: 2026-07-13

---

**The hiring-agent project resolves Git remote reference issues by sanitizing GitHub URLs in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), validating authentication tokens, and automatically managing corrupted cache files in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) to ensure reliable candidate evaluation.**

The interviewstreet/hiring-agent repository is a Python-based hiring assistant that parses PDF resumes and enriches candidate profiles with public GitHub data. When troubleshooting Git remote references in this pipeline, you must address URL parsing errors, authentication header failures, and cache integrity issues that prevent the `github_data` dictionary from populating correctly.

## Why Git Remote References Fail in Hiring-Agent Workflows

The hiring-agent architecture follows a strict data-flow pipeline: **resume extraction** ([`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)), **GitHub enrichment** ([`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)), **data transformation** ([`transform.py`](https://github.com/interviewstreet/hiring-agent/blob/main/transform.py)), and **LLM scoring** ([`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)). When the pipeline contacts the GitHub API to resolve a candidate's remote repository URL, several failure points emerge:

Git remote references fail primarily due to three root causes: **malformed URLs** that bypass the `extract_github_username` regex, **missing authentication tokens** that trigger rate-limiting, and **corrupted JSON cache files** that prevent fresh API calls. Each failure type produces distinct symptoms in the evaluation logs, requiring specific remediation steps.

## Common Error Patterns and Solutions

The following diagnostic table maps symptoms to their root causes and fixes based on the source code implementation:

- **`GitHub token not found`**  
  The `GITHUB_TOKEN` environment variable is missing or incorrectly named. Fix by adding `GITHUB_TOKEN=your_token` to a `.env` file or exporting it directly in your shell.

- **`Invalid GitHub cache file`**  
  Corrupted JSON remains from a prior run in the `cache/` directory. Fix by deleting the specific `cache/githubcache_*.json` file or allowing the auto-removal logic in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) (lines 270‑293) to handle it.

- **`Failed to extract username`**  
  The input URL contains extra characters, trailing slashes, or points to an unconventional domain (e.g., `gitlab.com`). Fix by ensuring the URL follows the format `https://github.com/<username>` before passing it to `extract_github_username`.

- **`Rate limit exceeded`**  
  Too many unauthenticated requests hit GitHub’s API. Fix by supplying a valid personal access token via the `GITHUB_TOKEN` environment variable.

- **Empty `github_data` dictionary**  
  The remote URL could not be parsed, or the API call returned an error. Fix by verifying network connectivity, inspecting the URL format, and checking the error logs in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) (lines 287‑290).

## Resolving Git Remote Issues in the Codebase

### Handling Malformed GitHub URLs

In [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) (lines 116‑131), the `extract_github_username` function sanitizes input URLs before API calls. It trims whitespace, removes trailing slashes, and applies a regex to extract the username. This prevents malformed remote references from reaching the GitHub REST API.

### Managing Cache Integrity

The [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) module implements defensive cache handling between lines 270 and 293. It checks for existing `cache/githubcache_<pdf>.json` files, validates JSON integrity, and automatically removes corrupted files before attempting fresh API calls. This ensures that stale or broken remote reference data does not persist across evaluation runs.

### Validating API Authentication

All GitHub API interactions in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) require the `GITHUB_TOKEN` environment variable. Without this token, requests execute unauthenticated, exhausting the rate limit of 60 requests per hour instead of the authenticated 5,000. The code logs clear warnings when authentication headers are missing, allowing quick identification of credential issues.

## Implementation Examples

### Extracting Usernames from Remote URLs

The following example demonstrates how `extract_github_username` handles messy input strings:

```python
from main.github import extract_github_username

url = " https://github.com/   alice  "
username = extract_github_username(url)
print(username)  # → alice

```

This function normalizes whitespace and validates the domain before extracting the username, preventing malformed remote references from propagating downstream.

### Executing the Full Pipeline

Run the complete evaluation workflow from the command line to test Git remote resolution:

```bash
python main/score.py path/to/resume.pdf

```

This executes the full pipeline: parsing the PDF, detecting the GitHub URL via [`transform.py`](https://github.com/interviewstreet/hiring-agent/blob/main/transform.py), fetching profile data via [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), and building LLM prompts.

### Debugging with Cache Files

Access cached GitHub data directly to verify remote reference resolution without API calls:

```python
import json
from pathlib import Path

cache_path = Path("cache/githubcache_alice.json")
if cache_path.exists():
    data = json.loads(cache_path.read_text())
    print(data["profile"]["public_repos"])

```

The cache stores raw JSON from the GitHub API, enabling offline debugging and verification of remote reference data.

## Summary

- **URL sanitization** in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) (lines 116‑131) prevents malformed remote references from reaching the GitHub API by trimming whitespace and normalizing domains.
- **Cache validation** in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) (lines 270‑293) automatically removes corrupted JSON files to ensure fresh data retrieval.
- **Authentication** requires the `GITHUB_TOKEN` environment variable to avoid rate-limiting and ensure reliable access to remote repository metadata.
- **Error logging** in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) (lines 287‑290) provides clear diagnostics when remote references cannot be resolved, enabling rapid troubleshooting.

## Frequently Asked Questions

### What causes "Failed to extract username" errors in hiring-agent?

This error occurs when the input string contains extra spaces, trailing slashes, or non-GitHub domains that bypass the regex in `extract_github_username`. Ensure URLs follow the strict `https://github.com/<username>` format before processing.

### How do I fix rate limit exceeded errors when fetching GitHub data?

Supply a valid GitHub Personal Access Token via the `GITHUB_TOKEN` environment variable. Without authentication, the pipeline is limited to 60 API requests per hour; authenticated requests allow up to 5,000.

### Where does the hiring-agent store GitHub API cache files?

The system stores responses in `cache/githubcache_<pdf_filename>.json` files within the project root. These files persist raw GitHub API responses to avoid repeated calls and enable offline debugging.

### How do I clear corrupted GitHub cache data?

Delete the specific `cache/githubcache_*.json` file associated with your candidate, or allow the automatic cleanup logic in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) to remove it when JSON parsing fails. Restart the pipeline to populate fresh data.