Your GitHub profile is often the first thing an employer, a collaborator or an open-source maintainer sees about you as a developer. They click your name on a pull request or a CV link and land on github.com/your-username. In a few seconds they form an impression: who is this person, what do they build, and is their work easy to understand?
A good profile works like a small portfolio: a short introduction, your best projects pinned at the top, and READMEs that show each project in action. A beginner with three well-presented projects can impress more than someone with fifty unexplained ones.
In this lesson you'll create a profile README, choose what to pin, write a useful bio, polish project READMEs, and understand the contribution graph, so your profile shows your work at its best.
The profile README
GitHub has a special feature: create a public repository with exactly the same name as your username, add a README.md, and its contents appear at the top of your profile page.
- Click + then New repository.
- Name it exactly your username, for example
samleefor the user samlee. GitHub shows a message confirming it's your special repository. - Tick Add a README file and create it.
- Edit the README with Markdown and commit. Your profile updates immediately.
Keep it short and scannable: who you are, what you're learning or building, how to reach you. A few lines and a list of highlights work better than a wall of badges and animations.
Pins, picture and bio
- Pinned repositories: on your profile, click Customize your pins and choose up to six repositories to show at the top. Pin your best, most finished work, not your newest.
- Profile picture: a clear photo or a simple, recognisable image helps people remember who you are across issues and pull requests.
- Bio and details: click Edit profile to add a one-line bio, location, website (such as your GitHub Pages portfolio) and social links.
Each pinned repository shows its description and main language, so give every repository a one-sentence description in its About box, plus topics like javascript or portfolio to help people find it.
READMEs that sell a project
Anyone who clicks a pinned project lands on its README. A good project README answers, in order:
| Section | Answers |
|---|---|
| Title and one sentence | What is it? |
| Screenshot or demo link | What does it look like? |
| Features | What can it do? |
| Getting started | How do I run it? |
| Built with | Which technologies did you use? |
| What I learned (for learning projects) | What does it show about you? |
A live demo link, for example a site published with GitHub Pages, is the single most effective thing you can add: people can see your work in one click.
The contribution graph
The green squares on your profile show days you made contributions: commits to a repository's default branch, pull requests, issues and reviews. Commits only count if the email in your Git config is one of the emails on your GitHub account, which is why the introduction lesson set it up.
Under the graph's settings you can choose to show private contributions as anonymous squares. Don't chase a perfect streak: steady, meaningful work on a few projects says more than a commit every day for its own sake.
GitHub Profile Syntax
Profile checklist
Repository named <username> with a README.md -> profile README
Profile > Customize your pins -> up to 6 pinned repos
Profile > Edit profile -> picture, bio, links
Repository > About (gear icon) -> description, website, topics
Repository > Settings > Archive -> hide old experiments
git config --global user.email <github email> -> commits count on your graphGitHub Profile Summary
- A public repository named exactly after your username shows its README on your profile.
- Pin up to six of your best repositories, each with a description and topics.
- Add a picture, a one-line bio and a link to your portfolio site.
- Good project READMEs explain what, show a screenshot or demo, and explain how to run it.
- Contributions count only when your Git email matches your GitHub account; quality beats streaks.
GitHub Profile Examples
Each example shows the code, the output it produces and what each part does.
A complete profile README
# Sam Lee
Junior web developer in Leeds. I build accessible, fast websites
with HTML, CSS and JavaScript, and I'm currently learning Python.
## Projects I'm proud of
- **[Recipe Box](https://samlee.github.io/recipe-box/)**: search and save recipes, works offline
- **[Budget Buddy](https://github.com/samlee/budget-buddy)**: a Python script that sorts bank exports into categories
- **[Portfolio](https://samlee.github.io/)**: my personal site, built from scratch
## Currently
- Learning: Python and SQL
- Contributing to: open-source accessibility checkers
## Contact
sam.lee.dev@example.com · [LinkedIn](https://www.linkedin.com/in/samlee-dev)Shown at the top of github.com/samlee:
Sam Lee
Junior web developer in Leeds. I build accessible, fast websites...
Projects I'm proud of
• Recipe Box: search and save recipes, works offline
• Budget Buddy: a Python script that sorts bank exports...
• Portfolio: my personal site, built from scratch
Currently / Contact sectionsLine-by-line explanation
- Lines 1 to 4A name and two sentences say who you are and what you do.
- Lines 6 to 9Linked projects, each with a one-line description of what it does.
- Lines 11 to 13Shows you're actively learning and contributing.
- Lines 15 to 16Make it easy to get in touch.
Describing a repository
Repository: recipe-box
About:
Description: Search, save and plan recipes. Works offline as a PWA.
Website: https://samlee.github.io/recipe-box/
Topics: javascript pwa html css accessibility
README:
# Recipe Box
## Features / Getting started / Built with / What I learnedOn the profile, the pinned card shows the name, description,
main language (JavaScript) and star count. Clicking it opens
a README with a screenshot and a live demo link.Line-by-line explanation
- Lines 2 to 5The About box, edited with the gear icon on the repository page.
- Line 5Topics make the project appear in GitHub's topic searches.
- Lines 6 to 9The README leads with a screenshot so visitors see the result immediately.
Making your commits count on your profile
git config --global user.email
git config --global user.email "12345678+samlee@users.noreply.github.com"
git config --global user.email
git commit --amend --reset-author --no-editsam@laptop.local
12345678+samlee@users.noreply.github.com
[main 5d1c2e9] Add search box
1 file changed, 14 insertions(+)Line-by-line explanation
- Line 1Check which email your commits use. This one isn't on the GitHub account, so commits won't show on the graph.
- Line 2GitHub gives every account a private "noreply" address, found under Settings, Emails. Using it keeps your real email out of public commit history.
- Line 4Fix the author of your latest, unpushed commit. Future commits use the new email automatically.
Common GitHub Profile Mistakes
A profile full of unexplained repositories
test, test2, new-project, untitled, project-final-v3 (no descriptions, no READMEs)3 pinned projects, each with a description, screenshot, live demo and README
Old experiments archived or made privateThe wrong repository name
Repository named "profile" or "Sam-Lee-README" -> nothing appears on the profileRepository named exactly "samlee" for user samlee, public, with README.mdCommits that don't show on your graph
git config --global user.email "sam@laptop.local" # not on your GitHub accountgit config --global user.email "sam.lee.dev@example.com" # an email added to GitHubGitHub Profile in Real Projects
Profiles in hiring and collaboration
Hiring managers often open a candidate's GitHub link, and maintainers glance at a contributor's profile before reviewing a first pull request. A clear profile with live demos is worth an evening's work.
GitHub Profile FAQ
How do I keep my email address private on GitHub?
In your email settings, turn on the option to keep your email addresses private. GitHub then gives you a noreply address to use as your Git user.email, so commits still link to your account without exposing your real address. Use it with git config --global user.email.
Why doesn't my contribution graph show work in private repositories?
By default, contributions to private repositories aren't shown publicly. You can turn on private contributions in your profile settings; visitors then see the counts in your graph, but not which repositories or what the work was.
How do I set a status on my GitHub profile?
Click your profile picture and choose to set a status. You can add an emoji and a short message such as "On holiday until Monday", and mark yourself as busy so others know you may reply slowly. You can also make it clear automatically after a set time.
Can an organization have a profile README?
Yes. Create a public repository called .github in the organization and add a profile/README.md file. Its content appears on the organization's overview page, which is a good place for a welcome message and links to key projects.
Should I delete old or unfinished repositories from my profile?
Not necessarily. Pin your best work so it appears first, archive projects you've finished with, and make private anything you don't want to show. Deleting is permanent from your point of view, while archiving keeps the history and tells visitors the project is no longer active.
GitHub Profile Exercises
Answer each one and check it instantly. If you get stuck, open the hint before the answer.
For the user ada, what must the special profile repository be called?
Repository name: How many repositories can you pin to your profile?
What's the most effective thing to add to a project README?
Why might your commits not appear on your contribution graph?
What should you do with old experiments you don't want to be judged by?
GitHub Profile Quiz
5 questions to check what you learned.
Where does a profile README appear?
- In every repository
- In your email signature
- On GitHub's home page for everyone
- At the top of your GitHub profile page
What are repository topics for?
- Sorting commits
- Creating branches
- Labelling a repository so people can find it by subject or technology
- Setting permissions
Which counts as a contribution on the graph?
- Viewing a repository
- Starring a repository
- Logging in
- Commits to the default branch, pull requests, issues and reviews
What should a short profile README include?
- Every repository you've ever made
- Who you are, what you build or learn, highlights and how to contact you
- Your password hints
- Only badges
Why pin finished projects rather than your newest ones?
- GitHub requires it
- New repositories can't be pinned
- Visitors judge you by what they see first, so it should be your best, most complete work
- Pins expire