GitHub is far more than a Git host. It is a collaboration platform built around Git repositories, with features for issue tracking, code review, project management, and automation. Understanding its structure is essential for working on any professional or open-source project.
Repositories
A GitHub repository contains your project's Git history plus GitHub-specific features: Issues, Pull Requests, Actions, Pages, and more. Repositories can be:
- Public: Visible to everyone on the internet. Anyone can clone and fork.
- Private: Only visible to collaborators you explicitly invite.
- Internal: (GitHub Enterprise) Visible to all members of your organisation.
The README
The README.md file in the root of a repository is rendered on the repository homepage. It is the first thing visitors see. A good README includes:
- Project name and one-sentence description
- Badges (build status, version, license)
- What the project does and why it exists
- Installation and quick-start instructions
- Usage examples
- Contributing guidelines and license
Issues
Issues are GitHub's built-in task tracker. Every repository has an Issues tab. They are used for:
- Reporting bugs
- Requesting features
- Tracking tasks and to-dos
- Asking questions (though Discussions is better for that)
Issues support Markdown formatting, file attachments, @mentions, and references to commits and pull requests (Closes #42 in a PR description automatically closes Issue #42 when merged).
Labels and Milestones
- Labels: Coloured tags that categorise issues —
bug,enhancement,good first issue,help wanted. - Milestones: Group issues into a release or sprint with a due date and progress bar.
- Assignees: Assign issues to one or more people responsible for them.
Forking
A fork is a server-side copy of a repository under your own GitHub account. Forking is the foundation of the open-source contribution model:
- Fork the repository (click "Fork" on GitHub)
- Clone your fork to your local machine
- Add the original repo as a second remote named
upstream:git remote add upstream git@github.com:original/repo.git - Create a feature branch, make changes, push to your fork
- Open a Pull Request from your fork's branch to the original repository
To keep your fork up to date with the original:
git fetch upstream
git switch main
git merge upstream/main
git push origin mainStars, Watching, and Notifications
- Star: Bookmark a repository you find interesting. Stars are public and also signal popularity.
- Watch: Subscribe to notifications for all activity in a repository (issues, PRs, releases).
- Notifications: Manage in GitHub settings — be selective, or inbox zero becomes impossible.
GitHub Discussions
Discussions is a forum-style feature for repositories — better suited for open-ended conversations, Q&A, and announcements than Issues (which are meant to be actionable and closeable). Many open-source projects use Discussions for their community and reserve Issues for concrete bug reports and feature requests.
Repository Settings
Key settings every contributor should know about:
- Branch protection rules: Prevent direct pushes to main; require PR reviews and passing CI checks before merging.
- Code owners: A
CODEOWNERSfile automatically assigns reviewers to specific files or directories. - Security advisories: Privately report and track security vulnerabilities before they are publicly disclosed.