Your GitHub Is Not a Portfolio (and What to Do About It)

GitHub proves you can write code. It does not explain what you built, why it mattered, or what you were like to work with — and it does not show up when someone searches your name. Treat GitHub as your evidence locker, not your front door. The front door is a page you control that tells the story; GitHub is what a curious reader clicks into once the story has earned their attention.

If you only do one thing after reading this: keep your best repos clean and pinned, but stop sending people a raw github.com/yourname link as your introduction. Send them somewhere that frames the work first.

What GitHub is genuinely good at

This is not an argument against GitHub. For engineers it is one of the most credible artifacts you have, and it does several things no portfolio can fake:

• Proof you ship real code. Commits, history, and tests are hard to invent. A reviewer who opens a repo can see how you actually work, not how you describe it.
• Collaboration signals. Pull requests, reviews, and issue discussions show how you communicate in a codebase — often more telling than the code itself.
• Open-source credibility. A merged PR into a project people use is a reference that vouches for you.
• A home for the code. It is the right place to host the work. Nothing below suggests moving your code somewhere else.

Keep all of that. The problem is not GitHub. The problem is asking GitHub to be the thing it was never built to be.

What GitHub doesn't do for you

A GitHub profile is a file browser. It is organized for people who already want to read code, in the order Git happens to store it. Here is where that falls short as a first impression:

• It has no narrative. A repo answers "what is in this folder," not "what problem did this solve, what did you decide, and what happened." A reader has to reverse-engineer the story from the code, and most won't.
• Half your audience can't read it. Recruiters, hiring managers, founders, and clients are often not engineers — or are engineers who don't have twenty minutes to spelunk your src directory. They bounce.
• A README is documentation, not a case study. It tells someone how to run the project. It rarely says why the project exists, what was hard, or what you'd do differently.
• The green squares mislead. The contribution graph rewards volume and public activity. Your most important work — done in private company repos — is invisible, while a week of trivial commits looks productive. Strong engineers often have sparse-looking graphs.
• It doesn't rank for your name. Search your name and your GitHub profile rarely wins the top spot, and when it does, it shows a username and a wall of repo names, not a professional introduction. (More on why in Why Your Linktree Doesn't Rank — the same logic applies to any utility page.)

None of this means GitHub is doing a bad job. It is doing its job. Curating your work for a human deciding whether to hire you is simply a different job.

"But I pinned my best repos and wrote good READMEs"

Good — that is the right instinct, and it genuinely helps. Pinned repositories and a thoughtful README are the closest GitHub gets to a portfolio, and a clean profile beats a messy one every time.

But notice what you're doing: you're manually fighting the platform to make it tell a story it isn't structured to tell. You can't control the layout, you can't put a case study above the code, you can't add a project that lives in a private repo, and you can't make any of it rank for "Jordan Rivera engineer." You're curating inside a container built for browsing, not for persuading. At some point it's less work to give the work a real home and link out to the repos.

The setup that actually works

The fix is not "GitHub or a portfolio." It's both, with each doing what it's good at: a profile site as the front door that frames the work, GitHub as the evidence one click deeper.

The pattern: a clean, fast site that opens with who you are and three or four projects written as short stories — problem, your role, what you decided, what happened — each linking to the repo, the live demo, or the PR for anyone who wants the receipts. The site persuades; GitHub corroborates.

What to put on the front door

You don't need much. For an engineer, a strong front door is short:

1. A one-line identity. "Backend engineer, distributed systems, based in Berlin." Plain and specific. This is also the sentence search engines and AI assistants quote about you.
2. Three to five projects, written as case studies. For each: the problem, the constraints, the call you made, the outcome, and what you'd change. One paragraph each is enough. Link to the repo or demo.
3. A side project that shows range — only if it actually shows something. A finished, deployed small thing beats a folder of abandoned starters.
4. Where to find the rest. Links to GitHub, the live products, your name on a relevant PR. Evidence, gathered in one place.

Write-ups beat screenshots because they show judgment, and judgment is what senior reviewers are actually screening for. A pretty repo says you can code. A clear writeup says you can decide.

Make the front door findable

A portfolio nobody can find is just a private document. The same things that make a page rank for a person make engineers' sites rank too: a clean URL (yourname.com or path.cv/yourname), a fast server-rendered page, structured data that says "this is a person, here is their name, role, and location," and consistent details across your GitHub, LinkedIn, and site so a search engine can connect them as one person.

This matters more than engineers expect, because the highest-intent search anyone runs about you is your own name. We cover that fully in How to Control What Shows Up When Someone Googles Your Name, and the broader findability picture — recruiters and AI assistants both — in How to Get Found by Recruiters and by AI.

For the full structure of a developer site — what to show, what to skip, and how to keep it fast — see How to Build a Developer Portfolio That Actually Gets You Hired.

This is the shape Path is built for: your project writeups and your work history on one fast page you own, with the structured data already handled and your profile indexed in a directory recruiters can search by skill and city. The code stays on GitHub; the page that gets found is yours.

Common questions

Can't I just use GitHub Pages for my portfolio?+

You can, and for some engineers it's a fine choice — you control the HTML and it's free. The catch is that you're back to building and maintaining a site by hand, including the SEO, structured data, performance, and mobile layout. GitHub Pages hosts a site you build; it doesn't give you a portfolio out of the box. If you enjoy that work, it's a legitimate path. If you'd rather spend the time on the writeups, a dedicated platform handles the plumbing.

My best work is in private company repos. How do I show it?+

Write it up instead of linking it. You can't share the code, but you can describe the problem, the constraints, the approach, and the measurable outcome without exposing anything proprietary — keep numbers in ranges if exact figures are sensitive. A clear written case study of confidential work is often more impressive than a public repo, because it shows you can communicate impact, not just commit.

Does a sparse contribution graph hurt me?+

Not with anyone who understands engineering. The green squares mostly track public activity, and serious work in private repos doesn't show up. Don't manufacture commits to fill it in — reviewers can tell, and it signals the wrong priorities. Let your projects and writeups carry the weight.

Should I still put my GitHub link on my resume?+

Yes — but put your site first. Lead with the URL that frames the work (yourname.com), and list GitHub as one of the links someone can follow for proof. The site is the introduction; GitHub is the evidence behind it.