Mastering GitHub: A Comprehensive Guide

GitHub is more than a Git host — it's a collaboration platform with pull requests, code review, CI/CD pipelines, project management, and static site hosting. This guide covers the features you'll use most in real projects.

Repositories

Creating a repository:

1. Click + → New repository
2. Set visibility (public or private)
3. Initialize with a README, .gitignore, and license if starting fresh

Cloning:

git clone git@github.com:username/repo.git

Use SSH for cloning if you plan to push. Set up an SSH key under Settings → SSH and GPG keys first.

Pull Requests

Pull requests (PRs) are the primary collaboration mechanism on GitHub. A PR proposes merging changes from one branch into another and creates a space for code review.

Creating a PR:

1. Push your branch: git push origin feature-branch
2. Go to the repository on GitHub
3. Click Compare & pull request
4. Write a clear title and description explaining what and why
5. Request specific reviewers if needed

Merging strategies:

• Merge commit — preserves all commits and branch history
• Squash and merge — combines all PR commits into one (clean main branch history)
• Rebase and merge — replays commits linearly without a merge commit

For most projects, Squash and merge gives the cleanest main branch history.

Code Review

Reviewing a PR:

• Comment on specific lines by clicking the line number
• Use Suggest changes to propose exact edits the author can accept with one click
• Approve, request changes, or leave a comment-only review

Review best practices:

• Be specific and constructive: "This function will be slow for large inputs because it runs in O(n²) — consider using a Set here" is more useful than "this is slow"
• Separate blocking issues from nitpicks — use "nit:" prefix for optional style suggestions
• Approve when you're satisfied, even if there are minor nits that the author can fix

Branch Protection Rules

Protect your main branch to prevent direct pushes and require CI to pass before merging:

1. Go to Settings → Branches → Add rule
2. Set Branch name pattern: main
3. Enable:
   • Require pull request reviews before merging
   • Require status checks to pass before merging
   • Require branches to be up to date before merging
   • Do not allow bypassing these settings

GitHub Actions (CI/CD)

GitHub Actions automates workflows triggered by repository events. Workflow files live in .github/workflows/.

Example: run tests on every push and PR:

# .github/workflows/test.yml
name: Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Run tests
        run: pytest

Example: deploy on push to main:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/deploy.sh
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}

Store secrets under Settings → Secrets and variables → Actions and reference them as ${{ secrets.SECRET_NAME }}.

Issues and Project Management

Issues track bugs, tasks, and feature requests. Key practices:

• Use labels to categorize (bug, enhancement, help wanted, good first issue)
• Use milestones to group issues by release
• Reference issues in commits and PRs: Fix #123 automatically closes the issue when the PR merges

Projects (GitHub's built-in kanban) let you track work across repositories with a board or table view.

GitHub Pages

Host a static site directly from a repository for free:

1. Go to Settings → Pages
2. Set source: Deploy from a branch
3. Select main and /docs (or /root for simpler setups)

Your site is available at https://username.github.io/repo-name.

For Jekyll sites or custom static site generators, use a GitHub Actions workflow to build and deploy.

Useful GitHub CLI

The GitHub CLI lets you manage GitHub from the terminal:

gh repo clone user/repo
gh pr create --title "Add feature X" --body "Description"
gh pr list
gh pr checkout 42
gh pr merge 42 --squash
gh issue create --title "Bug: X fails" --label bug
gh issue list --assignee @me
gh workflow run deploy.yml

Collaboration Best Practices

• Keep PRs small — under 400 lines of diff is easier to review than 2000 lines
• Write descriptive commit messages — "Fix login redirect for unauthenticated users" is better than "fix bug"
• Use draft PRs for work in progress — signals to reviewers that it's not ready yet
• Delete branches after merging — GitHub offers this automatically; it keeps the branch list clean
• Pin important issues and discussions — use the pin feature to highlight active issues

Conclusion

GitHub's PR workflow, branch protection rules, and GitHub Actions cover the full development cycle from code to deployment. Start with branch protection and a basic CI workflow — even a simple "run tests" action dramatically improves code quality for any team project.