How GitHub Profile Enrichment Works in the Hiring Agent: A Complete Technical Guide

The Hiring Agent enriches candidate resumes by extracting GitHub usernames from URLs, fetching public profile data and repositories via the GitHub API, classifying projects as open-source or self-projects, and using an LLM to select the top 7 most impressive projects for evaluation.

The interviewstreet/hiring-agent repository automates technical candidate screening by performing comprehensive GitHub profile enrichment on resume submissions. This process transforms a simple GitHub URL into a structured JSON payload containing the candidate's public metadata, repository statistics, and contribution history. The enrichment pipeline is implemented entirely in Python and consists of five distinct stages that process data from the GitHub REST API.

Stage 1: Extracting the GitHub Username from Resume Data

The pipeline begins in github.py with the extract_github_username function (lines 16-28). This utility normalizes raw input strings—which may contain full URLs like https://github.com/torvalds or plain usernames—and applies regex patterns to isolate the GitHub username. The function handles various URL formats and edge cases, ensuring that only the valid username portion proceeds to the next stage.

Stage 2: Fetching Public Profile Metadata

Once the username is isolated, the fetch_github_profile function (lines 41-71) executes an HTTP GET request to the GitHub REST API endpoint https://api.github.com/users/<username>. This call operates without authentication by default, though it supports token-based authentication for higher rate limits. The function retrieves the following profile fields:

• username (login name)
• name (display name)
• bio, location, company
• public_repos, followers, following
• created_at, updated_at
• avatar_url, blog, twitter_username
• hireable status

This data is validated against the GitHubProfile Pydantic schema defined in models.py before proceeding.

Stage 3: Repository Analysis and Classification

The fetch_all_github_repos function (lines 18-94) retrieves the user's public repositories via https://api.github.com/users/<username>/repos. For each repository, the system performs several operations:

1. Filters out low-impact forks to focus on original work
2. Collects metadata including name, description, primary language, stars, forks, topics, and creation/update timestamps
3. Queries contributor data via the repository's contributors endpoint to compute the author's specific commit count and the total contribution count
4. Classifies the project type as either:
   • open_source: Multiple contributors indicate collaborative community work
   • self_project: Single contributor indicates personal development

This classification helps the evaluation engine understand the candidate's collaborative versus individual coding experience.

Stage 4: LLM-Powered Project Selection

Raw repository lists often contain dozens of entries, so the system uses AI to identify the most impressive work. The generate_projects_json function (lines 34-75) prepares the repository data and passes it to an LLM using the github_project_selection.jinja template located in prompts/templates/.

The template instructs the model to select exactly 7 unique "most impressive" projects based on metrics like stars, complexity, and contribution patterns. If the LLM fails to return sufficient unique entries, the code falls back to selecting the first 7 repositories from the sorted list. The LLM integration utilities are handled by llm_utils.py, which manages provider initialization and JSON extraction from model responses.

Stage 5: Final Data Assembly

The fetch_and_display_github_info function (lines 59-78) serves as the orchestration layer that combines the profile dictionary and the selected project list into a single JSON object. This final payload is consumed by downstream modules—specifically the evaluator logic in score.py—to assess the candidate's technical abilities based on their open-source footprint.

What Data Is Retrieved from GitHub?

The enrichment system captures two distinct categories of data, all stored as plain JSON without exposing private tokens or secrets.

Profile Fields:

• Identity: username, name, bio, location, company
• Metrics: public_repos, followers, following
• Links: avatar_url, blog, twitter_username
• Status: hireable, created_at, updated_at

Repository Fields:

• Core metadata: name, description, html_url (GitHub URL), homepage (live URL)
• Technology: primary language, topics, technologies list
• Statistics: stars, forks, open_issues, size
• Classification: project_type (open_source or self_project)
• Contribution metrics: contributor_count, author_commit_count, total_commit_count
• Status flags: fork, archived, default_branch
• Nested github_details object containing all raw API response fields

Implementation Example

You can trigger the enrichment pipeline programmatically or via command line:

# Enrich a resume containing a GitHub URL

from github import fetch_and_display_github_info

github_url = "https://github.com/torvalds"
enrichment = fetch_and_display_github_info(github_url)

print(enrichment["profile"]["name"])
print(enrichment["projects"][0]["name"])
print(enrichment["projects"][0]["github_details"]["stars"])

# Command-line usage

python -c "import github; github.main('https://github.com/torvalds')"

The resulting JSON structure follows this schema:

{
  "profile": {
    "username": "torvalds",
    "name": "Linus Torvalds",
    "bio": "Creator of Linux and Git"
  },
  "projects": [
    {
      "name": "linux",
      "description": "Linux kernel source tree",
      "github_url": "https://github.com/torvalds/linux",
      "live_url": null,
      "technologies": ["C"],
      "project_type": "open_source",
      "contributor_count": 800,
      "author_commit_count": 1500,
      "total_commit_count": 1200000,
      "github_details": {
        "stars": 164000,
        "forks": 54000,
        "language": "C"
      }
    }
  ],
  "total_projects": 7
}

Key Source Files

The GitHub profile enrichment feature is implemented across the following modules:

• github.py: Core implementation containing extract_github_username, fetch_github_profile, fetch_all_github_repos, and fetch_and_display_github_info. Handles API requests, project classification, and LLM integration.
• models.py: Defines the GitHubProfile Pydantic schema for data validation and type safety.
• prompts/templates/github_project_selection.jinja: Jinja2 template that controls LLM prompting for project selection.
• llm_utils.py: Helper utilities for LLM provider initialization and response parsing.
• score.py: Orchestrates the end-to-end evaluation pipeline, triggering GitHub enrichment when resume data contains GitHub URLs.

Summary

• GitHub profile enrichment in the Hiring Agent transforms GitHub URLs into structured candidate intelligence using a five-stage pipeline.
• The system extracts usernames via regex in extract_github_username, then fetches public data from the GitHub REST API using fetch_github_profile.
• Repositories are classified as open_source or self_project based on contributor counts, calculated via the fetch_all_github_repos function.
• An LLM selects the top 7 projects using the github_project_selection.jinja template, with fallback logic ensuring consistent output.
• All data—including profile metadata, repository statistics, and contribution counts—is assembled by fetch_and_display_github_info for consumption by the evaluation engine in score.py.

Frequently Asked Questions

Does the Hiring Agent require GitHub authentication tokens to fetch profile data?

No, the system operates without authentication by default, making requests to public GitHub API endpoints. However, it supports optional token-based authentication to increase rate limits and avoid throttling when processing high volumes of candidate resumes. The code never exposes or stores private tokens in the output JSON.

How does the system distinguish between open-source contributions and personal projects?

The fetch_all_github_repos function queries the contributors endpoint for each repository and counts unique contributors. Repositories with multiple contributors are classified as open_source, while those with a single contributor are classified as self_project. This distinction helps hiring managers understand whether the candidate primarily works collaboratively or independently.

What happens if a candidate has fewer than 7 repositories?

If the LLM fails to select 7 unique projects—or if the candidate has fewer than 7 repositories—the generate_projects_json function implements a fallback mechanism that selects the first available repositories from the sorted list. The pipeline always attempts to return up to 7 projects but will return fewer if the candidate's public profile contains limited data.

Is private repository data or access tokens exposed in the enrichment output?

No. The system only accesses publicly available GitHub API endpoints and stores data as plain JSON. No private repository information, access tokens, or secrets are retrieved or exposed in the final payload consumed by score.py or other downstream modules.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}