What to Put on GitHub and in a Portfolio

When a reviewer opens your GitHub link, they are not admiring your contribution graph. They have a stack of candidates and a few minutes for each, and they are looking for evidence that you can build something real, explain why you built it that way, and leave it in a state another engineer could pick up. Two or three well-chosen, well-documented projects do that better than forty forks and half-finished tutorials.

What a reviewer actually looks at

Roughly in the order a busy reviewer gets to them:

1. Pinned repositories. If you pin nothing, GitHub chooses what to show, and its choice may not be your best work.
2. The top of the README. What is this, why does it exist, and does it work? If the first screen does not answer that, many reviewers move on.
3. How to run it. One command or a short list of steps, with an example environment file. Nobody will spend an afternoon on your setup.
4. A live demo or a short recording, for anything with an interface or a public API.
5. One or two source files. Structure, naming, error handling, and whether the code matches what the README claims.
6. Tests, ideally running in CI. Even a handful of meaningful ones shows that you think about correctness.
7. Commit history. Steady commits with clear messages show how you work. A single “initial commit” containing an entire project makes a reviewer wonder where it came from.

Follower counts and contribution streaks matter far less than people think, and streaks kept alive by automated commits are easy to spot.

Do you need a personal website? It depends on the role. For backend, data, and infrastructure work, a tidy GitHub profile is enough. For frontend and mobile roles, a live site or an installable app is the portfolio, and the code behind it is the supporting evidence.

Choose two or three projects for the role you want

A portfolio is an argument for one kind of job. Pick projects that show the signals a panel for that role looks for, and archive or hide the rest.

Target role	A project that fits	What to make visible
Backend developer	An API with authentication, a relational database, a background job, and rate limiting	Schema design, error handling, tests, a Docker Compose setup
Frontend developer	A responsive app built on a real public API, fully usable with a keyboard	State management, loading and error states, accessibility, a live link
Data engineer	A scheduled pipeline that loads a public dataset into a warehouse	Idempotent loads, data-quality checks, what happens on a rerun
ML engineer or data scientist	A model on a real dataset, compared against a simple baseline	Evaluation choices, error analysis, reproducible training
DevOps or cloud engineer	Infrastructure as code and a CI/CD pipeline for a small service	Terraform modules, pipeline stages, monitoring, teardown steps

One substantial project beats three thin ones. If you target two role families, keep a strong project for each and pin them in order of priority. Each role guide has more project ideas for that role.

For freshers and off-campus applicants, projects carry the weight that work experience carries for everyone else, and interviews often open with one. If a project was a group effort, such as a final-year college project, say in the README exactly which parts you built; panels will ask, and a vague answer undoes the project’s value. The guide to landing a first software job covers the rest of a fresher’s search.

Open-source work counts too, if it is real. One merged pull request to a maintained project, with the review discussion visible, shows you can work in someone else’s codebase and take feedback. Typo fixes in documentation are fine to make, but do not present them as the centrepiece.

Tutorial clones: why they hurt, and how to rescue one

Reviewers have seen the same to-do lists, weather apps, and streaming-site clones from popular courses many times over. A clone proves you can follow instructions, which is not what the panel is testing. If you built one while learning, you do not need to delete it. Make it yours:

• Add a feature the course did not cover, preferably a hard one: offline sync, search, role-based access, or payments in a sandbox.
• Replace the toy data with a real public dataset or API.
• Add tests and a CI workflow.
• Deploy it, and write down what broke along the way.
• State in the README what came from the course and what you added.

That last point persuades more than pretending ever could. Panels respect a candidate who says, “The base came from a course; the caching layer and the tests are mine, and here is why I built them that way.”

Write a README that sells your decisions

Code shows that you can build; a README shows judgement. Use this structure:

1. One-line summary: what it does and for whom. For example: “A rate-limited URL shortener with click analytics, built to learn Redis and PostgreSQL under realistic load.”
2. Demo: a live link, a short recording, or screenshots.
3. Running it locally: prerequisites, one command, and an example environment file.
4. Architecture: a few sentences or a simple diagram of the main parts.
5. Decisions and trade-offs: the section most candidates skip. For example: “PostgreSQL rather than MongoDB, because reports join clicks to links. A token bucket in Redis for rate limiting, because it allows short bursts without the double-rate spike a fixed window permits at its boundaries.”
6. Testing: what is covered, how to run it, and what is not tested and why.
7. Limitations and next steps: what you would change with more time or at a larger scale.

Interviewers often open a project discussion with “why did you build it this way?” A decisions section means you have already rehearsed the answer.

Presenting work you cannot share

Engineers at services companies and GCCs often have years of work under NDA and almost no public code. Reviewers know this. Never upload employer code, even with names changed: it can breach your contract, and it worries any reviewer who notices. Instead:

• Write a case study. One page per project, on a personal site or in a repository: the problem, your role, the architecture redrawn without confidential detail, your decisions, and the outcome in relative terms (“halved the nightly batch window”) rather than business figures.
• Rebuild a pattern, not the product. A small public repository with a generic version of something you solved at work, such as an idempotent event consumer or a feature-flag service, written from scratch on your own time and equipment.
• Read your employment agreement first. Many contain confidentiality and intellectual-property clauses that can reach side projects. This is general information rather than legal advice; if a clause is unclear, ask HR before you publish.
• Say it plainly in interviews. “I can walk you through the design, but I can’t show the code” is a complete and respected answer.

Hygiene that reviewers notice

• No secrets in the history. An API key deleted in a later commit is still in the repository history. Revoke or rotate any key that was ever committed, then clean the history.
• A proper .gitignore that keeps out node_modules, build output, virtual environments, and .env files.
• A licence file if you want others to be able to reuse the code.
• Archived experiments. Archive or make private the forks and abandoned projects you would not want to discuss in an interview.
• A short profile README: who you are, the roles you want, and links to your pinned projects.
• Names a stranger can understand: payments-reconciliation-demo, not project-final-2.

Portfolio checklist

• Two or three pinned projects that match one target role.
• Each README covers what, why, how to run, decisions, and limitations.
• Each project runs from a clean clone using only the documented steps; test this in a fresh container or on a friend’s machine.
• Your main project has tests that run in CI.
• Anything visual has a live demo or a recording.
• The commit history shows real progress with clear messages.
• No secrets, no employer code, and no untouched tutorial clones on display.
• Your resume links to specific projects, not just your profile (see the ATS-friendly resume guide).
• You can talk through each pinned project for fifteen minutes, including what you would do differently. The same habit pays off when you present take-home assignments.