How to build a standout GitHub profile README for 2027
How to build a GitHub profile README: the username repository rule, a 19-line sample, six pinned slots and what GitHub's own career guide says to include.
A GitHub profile README is the README.md file of a public repository named exactly like the username, and GitHub shows it on the profile page. To build one, create that repository with the Add README option on, replace the template with a short introduction and linked projects, and pin three to five repositories. GitHub's guide warns that hiring managers look at projects for only a couple of minutes.
How do you create a GitHub profile README?
Creating a profile README takes six steps, all documented in GitHub Docs as of 7 November 2026, and the finished file appears on the profile once the repository meets four conditions, listed after the steps.
- Select New repository from the plus menu in the upper-right corner of any GitHub page.
- Type a repository name identical to the username. For the username octocat, the repository must be named octocat.
- Choose Public.
- Switch Add README to On and select Create repository.
- Select Edit README. GitHub pre-fills the file with a template for inspiration.
- Replace the template with your own content and commit it.
GitHub shows the file on the profile only when four conditions hold: the repository name matches the username, the repository is public, the file is named README.md in the root, and the file has some content. A public repository with the username as its name that was created before July 2020 does not show automatically, and its README can be put on the profile with the Share to profile button. Profile READMEs are not available to managed user accounts.
What should a developer put on a GitHub profile?
GitHub's guide to using a profile on a resume suggests a short bio, then a profile README with an introduction, skills, professional experience, best projects, and achievements or awards. The table below turns that list into a build plan, with the limits GitHub states where it states one.
| Part of the profile | What to put there | Limit or note |
|---|---|---|
| Bio | One sentence: who you are and what work you want | Limited to 160 characters |
| Profile README introduction | Two lines on your background and the role you want | Rendered from GitHub Flavored Markdown |
| Skills | Languages and tools you can show in a repository | Skills with no linked project ask the reader to trust you |
| Best projects | Two or three projects with one line each on what they do | Pin them too; pins hold up to six items |
| Experience and achievements | Work, internships, awards or certifications | GitHub suggests non-technical skills such as communication can go here |
| Contact | One email address or a social link | Anything on a public profile is visible to all GitHub users |
| Hiring status | Available for hire, under Settings and then Jobs Profile | Optional |
GitHub also allows links to social accounts, a profile name that need not match a real-world identity, and a status message. Its profile reference warns that any detail added to a public profile can be seen by every GitHub user, so a phone number or home address does not belong there.
What does a sample GitHub profile README look like?
A profile README works best as a short page that a hiring manager can read in under a minute. Take a hypothetical fresher in Pune applying for backend roles. The 19 lines below hold an introduction, two linked projects, a skills table and one contact line. Every bracketed part is a placeholder, and the project names are invented.
# Hi, I am [Your Name]
Backend developer in [City], building APIs in Python and learning cloud deployment. Open to junior roles.
## What I am working on
- [project-one](link-to-repo): a REST API with tests and a live demo
- [project-two](link-to-repo): a CLI tool that cleans CSV files
## Skills
| Area | Tools |
| --- | --- |
| Languages | Python, JavaScript, SQL |
| Tools | Git, Docker, Postman |
## Contact
Email: your.name@example.comGitHub's Markdown renderer turns this file into one top heading, three section headings, a two-item list with links, a two-row table and a contact line with a mail link. GitHub also supports the HTML picture element, alert blocks such as NOTE and TIP, emoji codes and relative image paths, so extras are possible. They are optional, and a page with none of them still reads clearly.
Which repositories should be pinned?
Pin three to five repositories, because GitHub's guide recommends 3 to 5 projects and the profile holds at most six repositories and gists combined. The pins are set through Customize your pins above the Popular repositories or Pinned section, and they can be reordered by dragging.
GitHub's advice is to pick projects that show different skills and match the jobs being applied for, and to mix projects you own with open source contributions. Owned projects can be improved at will, while contributions show that you can work in someone else's codebase.
Each pinned repository carries its own README, which should list the key features, how to set up and run the project, an example or demo, and how to test it. The About box on the repository can hold a short description, a website link and topic tags.
Projects need not be apps: a repository can hold a spreadsheet model with a README that explains it. A hypothetical analyst could pin a workbook that uses the formulas covered in the Excel guide or a three-statement financial model. A separate guide on writing a project README covers that file in more detail.
Does the contribution graph matter?
The contribution graph counts only some actions, and it is easy to misread. According to GitHub Docs, creating a repository and forking a repository always count. Opening an issue, proposing a pull request, reviewing a pull request, opening or answering a discussion and making a commit count only when they meet GitHub's criteria.
For commits, the email address must be linked to the GitHub account, the commit must be in a standalone repository rather than a fork, and it must be on the default branch or the gh-pages branch. One more condition must hold: the user is a collaborator or organisation member, has forked the repository, or has opened a pull request or issue in it. New contributions can take up to 24 hours to appear, and squashing or force-pushing history can leave the graph counting commits that no longer exist in the visible history.
Work in private repositories can still be shown. When private contributions are made public, viewers see only how many contributions were made each day, with no details. Because the graph depends on these rules, a quiet or patchy graph says little about skill, and the pinned projects say more.
Do recruiters look at GitHub profiles?
GitHub's own career guide assumes hiring managers do open candidate profiles, and it says they usually consider many applicants for each role and will only look at projects for a couple of minutes. That advice is vendor guidance, not a survey of recruiters in India or anywhere else.
The practical reading is to make the first screen count. The bio, the first lines of the README and the three to five pinned projects are what a short visit will cover. GitHub also offers an Available for hire setting under Jobs Profile that signals openness to job opportunities. GitHub's guide also suggests putting a link to the profile on a resume.
What mistakes weaken a profile README?
Six mistakes weaken a profile README, and each follows from a rule in GitHub Docs or from the fact that a hiring manager reads a profile for only a couple of minutes.
- Leaving GitHub's starter template in place, which gives the reader nothing specific.
- Renaming the repository or making it private, which removes the README from the profile.
- Pinning repositories that have no README, setup steps or demo.
- Listing skills with no linked project behind them.
- Committing with an email address that is not linked to the account, so the work never appears on the graph.
- Adding personal details that are visible to every GitHub user.
Where does a profile README fit alongside a learning programme?
A profile README only works if there are real projects to point to, so it follows the building, not the other way round. The Forward Deployed Engineer cohort, Leap by Masai is a Leap by Masai programme for engineers with hands-on technical experience, run as an in-person start in Goa, an online build phase and an in-person hackathon in Bangalore for qualifying participants, covering production Python, APIs, cloud deployment, LLMs, retrieval, agents, security and client engagement. Work built in a programme like that is the kind of material a profile README can link.
A separate guide on creating an effective profile README gives a second take on the same page.
Frequently asked questions
How do you create a GitHub profile README?
Create a new public repository whose name is exactly your GitHub username, switch Add README to On, and then edit the README.md file. GitHub shows the file at the top of your profile page as long as it sits in the repository root and has some content.
What should a developer put on a GitHub profile?
A short bio, a profile README with an introduction, skills, best projects and one contact line, and three to five pinned repositories. GitHub's guide adds that each pinned project needs its own README covering features, setup, a demo and tests, plus a repository description and topic tags.
Do recruiters look at GitHub profiles?
GitHub's career guide assumes hiring managers do, and warns that they will only look at projects for a couple of minutes. That is vendor guidance rather than a survey of recruiters, so treat the advice as a reason to keep the first screen short and specific.
Why is a GitHub profile README not showing?
The usual causes are a repository name that does not match the username, a private repository, a missing or empty README.md in the root, or a README that was removed. A public repository created before July 2020 may need the Share to profile button before it appears.
How many repositories can you pin on GitHub?
GitHub allows up to six pinned items, counting repositories and gists together. Its career guide suggests choosing three to five projects that fit the jobs you want. Pins are set through Customize your pins on the profile and can be reordered by dragging.
Do private repository contributions show on a GitHub profile?
They can, in a limited form. When private contributions are made public, people without access to the private repositories see only the number of contributions made each day. GitHub Docs says they do not see specific details of that work.
Next step
Build the repository, paste the sample above, replace every bracket and pin three finished projects, then reread the page as a hiring manager would in two minutes. For engineers who want projects built around production Python, APIs and cloud deployment, the Forward Deployed Engineer cohort, Leap by Masai page lists the phases and what each one covers.