GitHub Essentials

GitHub is the de facto platform for hosting Git repositories, collaborating on code, and managing software projects. This page covers the core workflows every developer uses daily.

Repositories & Forks

A repository (repo) is a project container holding all files and history. Forking creates your own copy of someone else's repo under your account, enabling you to propose changes via pull requests.

# Create a new repo on GitHub via CLI
gh repo create my-project --public --clone
gh repo create my-project --private --clone

# Fork a repo and clone your fork
gh repo fork owner/repo --clone
cd repo
git remote -v
# origin    https://github.com/YOU/repo.git (fetch)
# upstream  https://github.com/owner/repo.git (fetch)

# Sync fork with upstream
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

# Clone with specific depth (faster for large repos)
git clone --depth 1 https://github.com/owner/repo.git

# View repo info
gh repo view owner/repo
gh repo view owner/repo --web   # Open in browser

Pull Requests

Pull Requests (PRs) are the primary mechanism for proposing changes. They enable code review, discussion, CI checks, and controlled merging.

# Standard PR workflow
git checkout -b feature/user-auth
# ... make changes ...
git add -p                              # Stage hunks interactively
git commit -m "feat: add JWT authentication"
git push -u origin feature/user-auth

# Create PR via CLI
gh pr create --title "Add JWT authentication" \
  --body "Implements RS256 JWT auth with refresh tokens" \
  --base main \
  --reviewer alice,bob \
  --label "feature,auth"

# List and view PRs
gh pr list
gh pr list --state all --author "@me"
gh pr view 42
gh pr view 42 --web

# Check out someone else's PR locally
gh pr checkout 42

# Merge a PR
gh pr merge 42 --squash --delete-branch
gh pr merge 42 --rebase
gh pr merge 42 --merge   # Merge commit

# Review a PR
gh pr review 42 --approve
gh pr review 42 --request-changes --body "Please add tests"

Issues

# Create an issue
gh issue create --title "Button not rendering on Safari" \
  --body "Steps to reproduce..." \
  --label "bug" \
  --assignee "@me"

# List issues
gh issue list
gh issue list --label "bug" --state open
gh issue list --assignee "@me"

# View and close issues
gh issue view 15
gh issue close 15 --comment "Fixed in PR #42"
gh issue reopen 15

# Link issues to PRs in commit messages / PR bodies
# GitHub auto-closes issues when PR merges:
# Closes #15, Fixes #16, Resolves #17

Code Review Workflow

Effective code review is a skill. GitHub provides inline comments, suggestion blocks, and required review policies via branch protection rules.

# Branch protection rules (set via GitHub UI or API):
# - Require pull request reviews before merging
# - Require status checks (CI) to pass
# - Require branches to be up to date
# - Require signed commits
# - Restrict who can push to main

# Best practices for reviewers:
# 1. Review in small chunks (< 400 lines per PR)
# 2. Use "suggestion" blocks for concrete code changes
# 3. Distinguish blocking (must fix) vs non-blocking (nit) comments
# 4. Approve only when all concerns are addressed

# CODEOWNERS file - auto-assign reviewers based on file paths
# File: .github/CODEOWNERS
# * @org/core-team              # Default owner for all files
# /src/auth/ @alice @bob        # Auth team owns auth directory
# *.ts @org/frontend-team       # TS files → frontend team
# /infra/ @org/devops           # Infra files → devops team

# Draft PRs - mark as not ready for review
gh pr create --draft --title "WIP: Refactor auth module"
# Convert draft to ready
gh pr ready 42

Releases & Tags

# Create a release
gh release create v1.2.0 \
  --title "v1.2.0 - Performance improvements" \
  --notes "## Changes
- Reduced bundle size by 30%
- Fixed memory leak in data fetcher" \
  --latest

# Create release from tag with auto-generated notes
gh release create v1.2.0 --generate-notes

# Upload assets to a release
gh release upload v1.2.0 ./dist/app-linux-amd64 ./dist/app-darwin-amd64

# List releases
gh release list

# View latest release
gh release view