How the GitHub Résumé Opt-In Mechanism Works: Star-Based Access Control

The GitHub Résumé opt-in mechanism works by verifying that a user has publicly starred the resume/resume.github.com repository via the GitHub API, granting access to the résumé generator only after this explicit star-based consent is detected.

The unofficial GitHub Résumé service at resume/resume.github.com implements a privacy-first access control system that requires users to actively endorse the project before exposing their profile data. This GitHub Résumé opt-in mechanism operates entirely client-side, checking the live GitHub API during page load to determine whether to render the résumé or display an opt-out notice.

How the GitHub Résumé Opt-In Mechanism Verifies Access

Initiating the Check via run()

When a visitor loads a résumé page, the JavaScript entry point in js/githubresume.js extracts the GitHub username from the URL query string and immediately invokes the run() routine. This function orchestrates the verification flow before any profile data renders, ensuring the opt-in check completes first.

The Star Detection Function

The core logic resides in github_user_starred_resume(username, page). This function queries the public GitHub API endpoint https://api.github.com/users/<username>/starred with pagination set to 100 items per request (per_page=100). It recursively searches through the user's starred repositories until it finds resume/resume.github.com or exhausts the list.

The function returns specific status codes:

• true – The user has starred the repository and is opted in
• false – The user has not starred the repository
• "api_limit" – GitHub API rate limit exceeded (HTTP 403)
• "not_found" – User not found or other API error (HTTP 404)

Client-Side Implementation Details

Inside js/githubresume.js, the detection algorithm iterates through paginated API responses using a synchronous AJAX call. When the repository full_name matches resume/resume.github.com, the function immediately returns true:

$.each(repos, function(_, repo) {
    if (repo.full_name === 'resume/resume.github.com') {
        star = true;
        return false; // break loop
    }
});

if (star) return true;
if (repos.length === 100) return github_user_starred_resume(username, page + 1);
return false;

If the current page returns 100 results without a match, the function recursively calls itself with page + 1 to check the next batch.

What Happens When You Haven't Opted In

The Access Denial Branch

Within the run() function, the return value of github_user_starred_resume determines which view template to load:

if (!starred || starred === 'api_limit' || starred === 'not_found') {
    // Load views/opt_out.html
} else {
    // Load views/resume.html or views/resumeOrgs.html
}

When starred evaluates to false, the application injects views/opt_out.html into the DOM instead of the résumé template.

The Opt-Out Interface

The views/opt_out.html template displays a notice explaining that the service is unofficial and requires users to star the repository to proceed. This creates a friction barrier that prevents automated scraping while allowing legitimate users to grant consent with a single click on the GitHub project page.

Rendering the Résumé After Opt-In

Once a user stars the repository, subsequent page loads trigger github_user_starred_resume to return true. The run() function then proceeds to fetch the appropriate résumé template—views/resume.html for individual profiles or views/resumeOrgs.html for organization accounts—and renders the full curriculum vitae with repository statistics and contribution graphs. The entry point index.html serves as the container that loads the necessary scripts and initiates this entire flow.

Manual Verification Using the GitHub API

You can verify opt-in status programmatically without loading the web interface. The following command checks whether a specific user has starred the repository:

# Replace USERNAME with the target GitHub login

curl -H "Accept: application/vnd.github.v3+json" \
     "https://api.github.com/users/USERNAME/starred" | \
jq '.[] | select(.full_name=="resume/resume.github.com")'

If the command returns a JSON object containing repository details, the user is opted in. An empty result indicates the user has not yet starred the repository.

To simulate the client-side validation logic from js/githubresume.js in your own scripts:

function checkOptInStatus(username) {
    var result = github_user_starred_resume(username, 1);
    if (result === true) {
        console.log('User opted in – render résumé');
        return true;
    } else if (result === 'api_limit') {
        console.log('GitHub API rate limit hit');
    } else {
        console.log('User not opted in – show opt-out page');
    }
    return false;
}

Summary

• The opt-in mechanism requires starring resume/resume.github.com to grant access to profile data.
• Verification occurs client-side via github_user_starred_resume(username, page) in js/githubresume.js.
• The API checks up to 100 starred repositories per request, paginating recursively until finding a match.
• Non-opted-in users see views/opt_out.html instead of their résumé data.
• The system handles API limits and missing users with specific error strings: "api_limit" for HTTP 403 and "not_found" for HTTP 404.

Frequently Asked Questions

Do I need to create a separate account to use the GitHub Résumé service?

No, the service uses your existing GitHub credentials. You opt in by starring the resume/resume.github.com repository while logged into GitHub. The JavaScript front-end detects this public star via the GitHub API when your résumé page loads.

How long does it take for the opt-in to activate after starring the repository?

The change is typically immediate. Since github_user_starred_resume queries the live GitHub API at page load time, refreshing your résumé URL right after starring should render your profile instead of the opt-out page. There is no caching delay in the verification logic.

Can I revoke access after generating my résumé?

Yes, simply unstar the resume/resume.github.com repository. The next time someone loads your résumé page, github_user_starred_resume will return false, triggering the display of views/opt_out.html instead of your profile data. The service performs a fresh API check on every page load with no persistent storage of your opt-in status.

Why does the service use a star-based mechanism instead of OAuth or logins?

The star-based approach provides a stateless, lightweight verification method that requires no server-side sessions or OAuth tokens. As implemented in js/githubresume.js, checking the public starred endpoint allows the static site to determine consent using only the GitHub username, keeping the architecture simple while respecting user privacy through explicit public endorsement.

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