What a Repository Page Actually Holds
Most of a GitHub repository is not code, and the parts that are not decide whether anybody can use the parts that are. Walk the README, the licence, releases, and the settings nobody sees until they matter.
Most of a GitHub repository is not code, and the parts that are not decide whether anybody can use the parts that are. Walk the README, the licence, releases, and the settings nobody sees until they matter.
The README is the front door, and it is just a file
GitHub renders README.md underneath the file list on every repository. It is not configuration and it is not special storage — it is a Markdown file in your repository, committed like any other, and the website happens to display it.
It is also one of the most useful files you will write. Somebody deciding whether to use, contribute to, or hire you off the back of this project reads this and usually nothing else.
What a README needs, in the order people need it
- →One sentence saying what this is — not what it does internally, what problem it solves
- →Why it exists, if there is an obvious alternative somebody already knows
- →How to run it: the exact commands, copy-pasteable, that take a stranger from clone to working
- →A screenshot or a short example if it produces anything visible
- →Where the docs are, if there are more
- →How to contribute, and the licence
# project-name One sentence about what this is and who it is for. ## Quick start ```bashgit clone https://github.com/you/project.gitcd projectnpm installnpm run dev``` Open http://localhost:3000. ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and pull requests welcome. ## Licence MIT — see [LICENSE](LICENSE).A handful of other files get special treatment on GitHub, all of them optional and all of them ordinary files in the repository. LICENSE belongs at the root; most of the others can live there or in a .github/ directory to keep the root tidy.
Detected and displayed in the sidebar. Without it, nobody may legally use your code.
Linked automatically when somebody opens an issue or a pull request.
Shown in the community profile. Expected on any project inviting outside contributors.
Powers the "Report a vulnerability" button and tells people where NOT to file a public issue.
Automatically requests review from the right people for the files a pull request touches.
A licence is what makes public code usable
This surprises people and it is worth being blunt about. Code on GitHub with no licence file is not open source. Copyright applies by default, and the default is that nobody may copy, modify, or use it. Making a repository public lets people view and fork it on GitHub, because you agreed to GitHub's terms — and nothing more.
A licence is how you grant the rest. There is no need to write one — pick a standard one, which is also what makes it recognisable to a company's legal review.
MIT
Do anything, keep the copyright notice, no warranty. Short, universally understood, and the default choice for most projects.
Apache 2.0
Like MIT, plus an explicit patent grant and a requirement to state changes. Preferred by companies for that patent clause.
GPL v3
Anyone who distributes a modified version must release their source under the GPL too. A deliberate choice, not a stricter MIT.
Tags and releases are two different objects
A tag is pure Git: a permanent name for one commit. Unlike a branch, it never moves.
$ git tag v1.2.0 # lightweight: just a name$ git tag -a v1.2.0 -m "Add CSV export" # annotated: name, tagger, date, message $ git tag # list them$ git push origin v1.2.0 # tags are NOT pushed by default$ git push --tags # push all of them$ git switch --detach v1.2.0 # look at the code as it was at that releaseThe line that catches everybody: git push does not push tags. You tag the release, you push, and the tag stays on your laptop. Use annotated tags for releases — they record who tagged it and when, and some tooling ignores lightweight ones entirely.
A release is a GitHub feature built on top of a tag. It adds release notes, downloadable binaries, and a pre-release flag. Every release has a tag; not every tag is a release.
Git. A fixed pointer to a commit. Works offline, exists in every clone, nothing to do with any website.
GitHub. A tag plus notes plus attached files. Lives on the website; not in your clone.
MAJOR.MINOR.PATCH — breaking change, new feature, bug fix. A convention people rely on to know whether an upgrade is safe.
Settings hold the decisions nobody sees
The Settings tab is where a repository stops being a folder and becomes a set of rules. A few of them matter far more than the rest.
Public or private. Going private later does not un-publish anything — clones, forks, and caches persist. Treat public as permanent.
What a clone checks out and what pull requests target by default. Renaming it is supported and GitHub redirects the old name for a while.
Branch protection and rulesets: required reviews, required checks, no force pushes. This is where a review process becomes enforced rather than agreed.
Which of merge, squash, and rebase are allowed, and whether the branch is auto-deleted. Turning off the ones your team does not want removes the daily decision.
Encrypted values available to Actions. The correct home for anything a workflow needs and nobody should read.
Who can push. Read, Triage, Write, Maintain, Admin — write access is the one that lets somebody push to a branch directly.
Stars, forks, and watches count three different things
The three numbers at the top mean different things, and only one of them is about code.
Star
A bookmark and a public thumbs-up. No notifications, no copy, no relationship. The nearest thing to a popularity score.
Fork
A real copy of the repository under your account, linked to the original. This is the one that does something — it is how you contribute without write access.
Watch
Subscribe to notifications: all activity, or just releases, or just issues. The only one that fills your inbox.
The remaining tabs are worth a tour once each. Insights holds the contributor graph, the commit frequency, the dependency graph, and Network — a visualisation of every fork and branch that is the fastest way to see whether a fork went somewhere the original did not. Security holds Dependabot alerts for known-vulnerable dependencies, secret scanning, and code scanning. On a public repository these are free; secret scanning is on by default, and Dependabot alerts are worth switching on.
A repository somebody else can actually use
- ✓A README whose first sentence says what this is
- ✓A LICENSE file, or nobody may legally use it
- ✓A description and a few topics, so it is findable
- ✓A .gitignore appropriate to the language
- ✓Branch protection on main if more than one person pushes
- ✓Dependabot alerts on, so you hear about a vulnerable dependency from GitHub rather than from a stranger
Key takeaways
- README.md is an ordinary Markdown file that GitHub happens to render. It is one of the most useful files in a repository.
- LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY and CODEOWNERS all get special treatment. LICENSE goes at the root; most others can live in .github/.
- Public code with no licence is not open source — copyright says nobody may use it.
- MIT for permissive and short, Apache 2.0 for the patent grant, GPL to require derivatives stay open.
- A tag is a permanent Git name for a commit; a release is a GitHub object built on a tag.
- git push does not push tags. Use git push origin <tag>.
- Branch protection is where an agreed review process becomes an enforced one.
- Going private later un-publishes nothing. Treat anything public as permanent.
- Deleting a repository destroys its issues and reviews; archiving keeps everything read-only.
- Stars are a bookmark, forks are a real copy you can push to, watching is what sends notifications.
Before you move on
Quick check
Answer these to unlock the next chapter: 3 of 4 to pass. You can retake it anytime.
Make a free account to read on
Every chapter is free — an account lets your course progress follow you from your laptop to your phone. No payment, no trial.