Awesome — we’ll cover the .github/ folder from a reader’s POV: what it is, how it changes what you see on GitHub, and how to quickly make sense of it in any repo.
What the .github/ folder is • Purpose: holds GitHub-specific config (templates, automation, repo metadata). It doesn’t ship in packages or affect runtime code. • Scope: affects issues, PRs, Discussions, security disclosures, CI (GitHub Actions), and repo presentation.
How it changes your experience • Issues/PRs: you’ll see structured forms or prefilled text when opening issues/PRs. • Automation: PRs may auto-label, auto-assign reviewers, run checks/tests, or block merges. • Docs & policies: contribution rules, code of conduct, and security reporting paths show up in dedicated UI entries. • Sponsorship: “Sponsor” button appears if configured.
Folder tour (what each file/dir means) • workflows/ → GitHub Actions. YAML files here define CI/CD and automations (tests, lint, deploy, labelers). • ISSUE_TEMPLATE/ • bug_report.yml, feature_request.yml → issue forms. • config.yml → controls default labels/assignees or disables blank issues. • PULL_REQUEST_TEMPLATE.md (or PULL_REQUEST_TEMPLATE/…) → default PR body. • FUNDING.yml → enables the Sponsor button (GitHub Sponsors, OpenCollective, etc.). • CODEOWNERS → defines who must review changes in certain paths. • labeler.yml / .yml under workflows/ → rules to auto-apply labels. • dependabot.yml → dependency update bot config. • renovate.json (sometimes lives here) → Renovate bot config. • SECURITY.md → how to report vulnerabilities; triggers the “Security policy” link. • CONTRIBUTING.md → displayed in PR/issue UIs; contributor guidance. • CODE_OF_CONDUCT.md → project conduct policy. • DISCUSSION_TEMPLATE/ → templates for GitHub Discussions (if enabled). • release.yml (rare) → release notes generation settings.
Inheritance & precedence (useful nuance) • Organization-level defaults: an org can host a special /.github repository. Its templates & workflows can apply to all repos that don’t override them. • Repo wins: if both org-level and local .github exist, the repo’s .github takes precedence for overlapping items. • Forks: automations in forks may be limited (e.g., Actions won’t run on secrets from upstream).
How to read a .github/ folder fast 1. Scan workflows/ first. • Key questions: When do jobs run? On push? pull_request? schedule? Are there required checks blocking merges? 2. Open CODEOWNERS. • Who auto-reviews certain files? This explains recurring review requests. 3. Peek at ISSUE_TEMPLATE/ & PR templates. • What’s the expected info when filing an issue? Are there forms (YAML) vs markdown? 4. Check CONTRIBUTING.md & SECURITY.md. • Any special rules (DCO, CLA, commit style), or private channel for security reports? 5. Look for bots. • dependabot.yml, labeler.yml, Renovate config → automated PRs/labels you’ll see in the feed.
What you’ll actually notice in the UI • Prefilled issue/PR bodies or form-like fields. • Automatic labels (e.g., area/frontend, type/bug) right after creation. • Auto-requested reviewers per path. • Checks appearing under PRs (lint, tests, build). Some may be required before merging. • Security policy and Sponsor button in the right sidebar.
Common gotchas (as a reader/contributor) • Actions are sandboxed: If your PR is from a fork, secrets aren’t available, so some jobs are skipped or run in “read-only” mode. • Required checks: Even if a maintainer approves, merge may be blocked until required workflows pass. • Templates can disable blank issues: If you don’t see “Open a blank issue,” it’s intentional (ISSUE_TEMPLATE/config.yml). • CODEOWNERS is path-sensitive: A tiny path mismatch can explain why the wrong reviewer was assigned (or none).
Mini-glossary (quick anchors) • Workflow job: A named set of steps (e.g., test) that runs in a runner VM/container. • Trigger: Event that starts a workflow (push, pull_request, workflow_dispatch, schedule). • Required check: A status that must be green to merge; configured in branch protection. • Issue form: YAML-based issue templates with typed fields (dropdowns, textareas).
Mental model (TL;DR) • “.github configures how we collaborate, not how we run code.” • “workflows/ = automation; templates = input structure; owners = accountability.” • “Org defaults apply unless the repo overrides them.”
If you want, send me a link or paste a tree of a specific repo’s .github/ and I’ll walk you through it line by line and call out the practical implications (labels, checks, review rules, release flow) in your terms.