Skip to content

GitHub Essentials

GitHub is git plus collaboration: a home for your git repositories with pull requests for review, issues for tracking, Actions for automation, and Pages for publishing.

Table of Contents

Installation / Setup

Repositories

# Create locally, connect to GitHub
git init && git add . && git commit -m "Initial commit"
gh repo create my-project --source=. --push --public   # GitHub CLI
# or create on github.com and:
git remote add origin git@github.com:you/my-project.git
git push -u origin main
Concept What it is
Repository A project folder + full git history
main The default, protected branch
Fork Your copy of someone else's repo
Star / Watch Bookmark / follow activity 
ssh-keygen -t ed25519 -C "you@example.com"   # creates ~/.ssh/id_ed25519(.pub)
cat ~/.ssh/id_ed25519.pub
# paste the public key into GitHub: Settings → SSH and GPG keys → New SSH key
ssh -T git@github.com                        # "Hi you! You've successfully authenticated"

Clone with git@github.com:you/repo.git (SSH) instead of https://....

Personal access tokens (for HTTPS / API / scripts)

  • Fine-grained tokens (recommended): Settings → Developer settings → Fine-grained tokens — pick only the repos and permissions needed, add an expiry.
  • Classic tokens: scope repo for full access — use sparingly.
  • Treat tokens like passwords: never commit them, never paste into code, use a secrets manager or GitHub CLI's auth.
gh auth login          # store credentials once, gh handles the rest

Core Syntax

Branch protection & workflows

# CLI workflow (mirrors the click-path below)
git switch -c feature/x && git push -u origin feature/x
gh pr create --title "Add X" --body "Closes #12"
gh pr view --web
gh pr merge --squash

On github.com: enable branch protection on main (Settings → Branches): require PR review, require status checks, block force-push. Data science teams do this so notebooks and code get reviewed.

Pull requests

A PR proposes merging branch A into branch B after review. Good PR anatomy:

  1. Clear title + description: what and why, link issues (Closes #12).
  2. Small scope — one feature/fix, easy to review.
  3. Conversation — reviewers comment; author pushes fixes; CI re-runs.
  4. Merge options: merge commit (keeps history), squash (one clean commit), rebase (linear).
gh pr list                # open PRs
gh pr checkout 123        # pull PR #123 locally
gh pr diff                # see the changes

Issues

gh issue create --title "Bug: NaN in split" --body "Steps to reproduce..."
gh issue list --assignee @me
gh issue close 12
Issue tools Purpose
Labels bug, good first issue, enhancement
Milestones group issues toward a release
Projects (beta) kanban-style planning
Templates standardize bug reports/feature requests

Conventions: #12 references an issue, Closes #12 auto-closes it when merged, and Fixes/Resolves work too.

Releases

  1. Tag a commit: git tag -a v1.0.0 -m "1.0.0" && git push origin v1.0.0
  2. github.com → Releases → Draft a new release → choose tag.
  3. Attach binaries/assets and notes; GitHub builds the zip/tarball automatically.
gh release create v1.0.0 --title "1.0.0" --notes "First stable"

Actions (CI/CD basics)

Workflow files live in .github/workflows/*.yml:

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install -r requirements-dev.txt
      - run: pytest
      - run: mypy src/

gh workflow run ci.yml      # trigger manually
gh run list / gh run view   # inspect runs

Common actions: actions/checkout, actions/setup-python, actions/cache, actions/upload-artifact. Secrets go in Settings → Secrets and variables → ${{ secrets.NAME }}.

Pages (free static hosting)

  • Push a branch (main) or folder (/docs, /gh-pages) → Settings → Pages → choose source.
  • Built-in themes for project sites; works with any static site (Jekyll, mkdocs, Quarto, custom HTML).
  • URL: https://<user>.github.io/<repo>/. For docs-heavy repos, mkdocs/Quarto → Pages is a common data-science setup.

Common Operations

Everyday PR flow

git switch -c feature/outlier-handling
# ... edits, commits ...
git push -u origin feature/outlier-handling
gh pr create --fill                 # title/body from commits
# reviewer approves → merge
gh pr merge --squash --delete-branch

Sync a fork with upstream

git remote add upstream https://github.com/original/repo.git
git fetch upstream
git switch main && git merge upstream/main
git push

Review someone's PR locally

gh pr checkout 123          # switches to that branch + fetches
# run the code, test it, comment on github.com or:
gh pr review --approve
gh pr review --request-changes --body "See comments"

Codespaces (cloud dev environment)

  • Open any repo → Code → Codespaces → Create codespace — full VS Code in the browser with the repo cloned.
  • Devcontainer (.devcontainer/devcontainer.json) pins Python version + extensions for reproducible setups.

Practical Examples

1. Open-source contribution flow

gh repo fork sklearn/scikit-learn --clone
git switch -c fix/docstring
# edit → commit → push
gh pr create --title "Fix docstring typo" --body "Small docs fix"

2. Notebook review workflow (data science)

# .github/workflows/ci.yml — run checks on every PR
#   - nbstripout (strip outputs) before commit
#   - pytest for the package code
#   - reviewers use gh pr checkout + Jupyter to eyeball notebook diffs

3. Automate issue → PR with linked keywords

PR body:

Closes #42
Fixes #13

Merging the PR automatically closes both issues.

Common Patterns

# Labels as a lightweight roadmap
gh label create "data science" --color "1d76db"
gh issue create --label "good first issue" ...

# Release + changelog from PRs
gh release create v0.2.0 --generate-notes

# Protect main from accidental pushes
# Settings → Branches → Add rule: require PR + checks on main

Best Practices

  • Protect main — no direct pushes; everything through reviewed PRs.
  • Small, focused PRs with linked issues get reviewed faster and merge cleaner.
  • Write good issue reports: reproducible steps, expected vs actual, environment.
  • Use SSH keys for daily git; fine-grained, expiring tokens for scripts.
  • Never commit secrets — GitHub revokes exposed tokens automatically and emails you; rotate them.
  • Review your own PR diff before requesting others — catch obvious mistakes cheaply.
  • Keep CI green on main; fix broken builds immediately.
  • Use Codespaces or devcontainers to make environments reproducible for the whole team.

Common Mistakes

Mistake Consequence Fix
Pushing directly to main Unreviewed changes in production branch Branch protection rules
Committing a .env/token Secret leaked; token auto-revoked Rotate secret; git filter-repo history cleanup
Giant PRs (5000 lines) Nobody reviews properly Split into small PRs
gh pr create without pushing Error: no commits on remote git push -u origin branch first
Merging stale PRs Conflicts & broken main Update branch (gh pr merge --update-branch) or rebase
Classic tokens with full repo scope Over-permissioned Fine-grained tokens, least privilege
Opening PRs from main Can't reuse the branch Always a feature branch

Troubleshooting

Symptom Cause Fix
Permission denied (publickey) SSH key not registered Add key in Settings; ssh -T git@github.com
Repository not found Wrong URL / no access Check owner/name; SSH vs HTTPS mismatch
gh: not logged in CLI not authenticated gh auth login
PR shows "This branch is out-of-date" main advanced Merge/rebase main into the branch
! [rejected] ... fetch first Remote has commits you lack git pull --rebase then push
Actions run but fail silently Workflow syntax/logic gh run view --log-failed; test locally with act
Token suddenly invalid Auto-revoked after leak Rotate; check security log; remove from code

Official Documentation

Last Updated

2026-09-06 — Initial version.