Special GitHub repos most developers never set up
Your username is a feature flag. Four repositories, two files, and the conditions nobody mentions.
I was tidying up my GitHub profile last week.
Pinned repos, a decent bio, the usual. Then I read something that made me stop: if you create a public repository with the exact same name as your username, GitHub takes the README out of it and renders it at the top of your profile.
No setting. No toggle in preferences. You name the repo correctly and it happens.
That felt like a strange enough design decision that I went looking for what else works this way. There are three more repositories and a couple of files. Some of them I’d been using for years without realising they belonged to the same pattern.
Here they are, with the bits that trip people up.
username/username — the profile README
Create a repository whose name matches your GitHub username, character for character. Put a README.md in the root. That file now renders on github.com/username, above your pinned repositories.
Four conditions, and all of them have to hold:
The repository has to be public. A private one gets you nothing, which catches people who make it private out of habit.
The file has to be README.md in the root. Not in docs/, not in .github/.
The file has to have content in it. GitHub’s docs spell this out, and they say the same thing about removal: emptying the README takes it off your profile just as surely as deleting it.
And if you created a repo with your username before July 2020, GitHub won’t pick it up automatically. There’s a “Share to profile” button on the repo page for exactly this case.
One more thing worth knowing if you’re on a work account: profile READMEs aren’t available to Enterprise Managed User accounts.
What goes in it is up to you. Mine is short. I’ve seen people run GitHub Actions on a schedule to rebuild theirs with recent commits, now-playing tracks, and blog posts. Whether that’s a good idea depends on how you feel about a repository that commits to itself every hour.
username.github.io — the site at the root
This is the one most people have already met, usually without noticing the rule behind it.
Publish any repository with GitHub Pages and it lands on a subpath: username.github.io/notes/, username.github.io/portfolio/. Publish a repository named username.github.io and it lands on the root: username.github.io/.
That’s what my own site runs on. One repo, no subpath.
A few details the name alone doesn’t tell you:
It’s the owner name, not just a user name. Organisations use the identical pattern, orgname.github.io. And if your account name has uppercase letters in it, you lowercase them in the repo name.
Creating the repo isn’t enough. You still pick a publishing source under Settings → Pages: a branch and a folder, or a GitHub Actions workflow. That branch can be any branch now, which wasn’t always true.
You get one of these per account. Project sites are one per repository, but the root site is a single slot.
Get Piyush Doorwar 💻’s stories in your inbox
Join Medium for free to get updates from this writer.
And if you point a custom domain at your user site, project sites for that owner get served under the custom domain too, not under username.github.io/. So the subpath rule above quietly stops applying.
.github — write your boilerplate once
This is the one I’d actually reach for at work, and it’s the least known of the four.
Create a repository called .github under your account or your organisation. Put CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, SUPPORT.md, GOVERNANCE.md, FUNDING.yml, your issue templates and your pull request template in it. Every other repository you own that doesn't have its own copy of one of those files now uses the one from .github.
For a team with thirty repositories where four have a CONTRIBUTING file and the rest don’t, that’s a real change for about ten minutes of work.
The lookup order inside each repository is .github/ folder, then the root, then docs/. If nothing turns up, GitHub falls back to your .github repository and walks the same three locations there.
Three things about it that aren’t obvious:
The .github repository has to be public. Private ones aren't supported. That means your CONTRIBUTING and SECURITY text is publicly readable even when the repositories consuming it are private. Usually fine. Worth knowing before you paste anything internal into it. (On Enterprise Cloud the repo can also be internal, except for issue and pull request templates, which still need it public.)
Issue templates are all-or-nothing. If a repository has any file in its own .github/ISSUE_TEMPLATE folder, none of your defaults are used for that repository. It doesn't merge the two sets.
You can’t default a LICENSE. GitHub is explicit about this, and the reasoning is good: a license file has to travel with the code when someone clones, packages, or downloads the project, so it lives in each repository. README is the same story, though for a duller reason: it’s simply not on the supported list.
org/.github with profile/README.md — the organisation's front page
Same repository, one extra job, and only for organisations.
In your organisation’s public .github repository, create profile/README.md. It renders on the Overview tab of the organisation's public profile, above the repository list. For anyone landing on your org page cold, that's the difference between a wall of repo names and an actual explanation of what the team does.
Note the asymmetry, because it catches people: personal accounts get the .github repository for default community health files, but not the profile/README.md path. A personal profile README lives at the root of username/username. Different repo, different path, different feature. And the .github repo's own root README does nothing for anybody — it's profile/README.md that drives the org page.
Public organisation profiles aren’t available with Enterprise Managed Users either.
org/.github-private — the same page, for members
Create a private repository called .github-private in the organisation, with a profile/README.md inside it.
The wording that gets used for this feature is usually wrong, including mine before I read the docs properly. It isn’t a visibility switch on one README. It’s a second README in a second repository, and both can exist at the same time.
Signed-in members of the organisation get a “View as” dropdown on the Overview tab with Public and Member options. The view defaults to Member if there’s either a members-only README or members-only pinned repositories. Non-members only ever see the public one.
Which makes .github-private a good place for links people actually need on day one: the onboarding doc, the runbook, where the deploy pipeline lives. An internal landing page that nobody has to bookmark, because it's on a page they'll open anyway.
Two files that work the same way
Not repositories, but the same idea one level down.
CITATION.cff in a repository root adds a "Cite this repository" button to the sidebar, with APA and BibTeX formats ready to copy. If you've published anything academic, or anything you'd like cited properly, this saves a lot of back-and-forth.
.gitattributes with a line like vendor/* linguist-vendored fixes the language bar. If your Python project shows up as 62% JavaScript because of one bundled minified file, this is the fix. linguist-language lets you override detection outright for a path.
What I’d do first
If you only do one, do the profile README. It takes five minutes, and it’s the first thing anyone sees when they open your profile from a job application or a conference talk.
If you run an organisation, .github is the one with the best return. Write the contributing guide once.
I’d like to make this list longer. If there’s a repo or file name GitHub treats specially that I’ve missed, tell me — I’ll add it.
