# GitHub — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "Knowledge Base Index" type: index updated: 2026-06-19 --- # Knowledge Base Index Master catalog of all wiki pages. Every page in the wiki must have an entry here. ## Concepts | Page | Tags | Confidence | Updated | |------|------|------------|---------| | [what-is-github](concepts/what-is-github.md) | github, git, overview | high | 2026-06-19 | | [repositories-and-git](concepts/repositories-and-git.md) | repositories, git, clone | high | 2026-06-19 | | [branches-and-merging](concepts/branches-and-merging.md) | branches, merge, protection | high | 2026-06-19 | | [pull-requests](concepts/pull-requests.md) | pull-requests, code-review | high | 2026-06-19 | | [issues-and-projects](concepts/issues-and-projects.md) | issues, projects, planning | high | 2026-06-19 | | [github-actions](concepts/github-actions.md) | actions, ci-cd, workflows | high | 2026-06-19 | | [actions-runners](concepts/actions-runners.md) | runners, github-token, oidc | high | 2026-06-19 | | [rest-api](concepts/rest-api.md) | rest, api, automation | high | 2026-06-19 | | [graphql-api](concepts/graphql-api.md) | graphql, api, queries | high | 2026-06-19 | | [github-cli](concepts/github-cli.md) | gh, cli, automation | high | 2026-06-19 | | [github-pages](concepts/github-pages.md) | pages, static-site, hosting | high | 2026-06-19 | | [github-packages](concepts/github-packages.md) | packages, registry, ghcr | high | 2026-06-19 | | [codespaces](concepts/codespaces.md) | codespaces, devcontainer | high | 2026-06-19 | | [authentication](concepts/authentication.md) | ssh, 2fa, passkey, pat | high | 2026-06-19 | | [code-security](concepts/code-security.md) | code-scanning, codeql, dependabot | high | 2026-06-19 | | [webhooks](concepts/webhooks.md) | webhooks, events, integrations | high | 2026-06-19 | ## Summaries | Page | Source | Key Topics | Created | |------|--------|------------|---------| | [docs-catalog](summaries/docs-catalog.md) | github/docs content | area map + reference spaces | 2026-06-19 | ## Syntheses | Page | Pages Compared | Created | |------|----------------|---------| | [ci-cd-pipeline](syntheses/ci-cd-pipeline.md) | repos+PR+branch-protection+actions+deploy | 2026-06-19 | ## Statistics - **Total pages**: 18 - **Concepts**: 16 - **Summaries**: 1 - **Syntheses**: 1 - **Sources ingested**: 295 github/docs pages across get-started, repositories, pull-requests, issues, actions, github-cli, rest, graphql, pages, packages, codespaces, authentication, webhooks, code-security - **High confidence**: 17 - **Medium confidence**: 1 --- title: "Actions Runners & Workflow Security" type: concept tags: [runners, self-hosted, github-token, oidc, secrets] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-actions-concepts-runners-index-md.md, raw/github_doc-content-actions-concepts-runners-github-hosted-runners-md.md, raw/github_doc-content-actions-concepts-security-github-token-md.md, raw/github_doc-content-actions-concepts-runners-larger-runners-md.md, raw/github_doc-content-actions-concepts-runners-runner-groups-md.md, raw/github_doc-content-actions-concepts-runners-runner-scale-sets-md.md, raw/github_doc-content-actions-concepts-runners-self-hosted-runners-md.md, raw/github_doc-content-actions-concepts-runners-support-for-arc-md.md, raw/github_doc-content-actions-concepts-runners-private-networking-md.md, raw/github_doc-content-actions-concepts-security-openid-connect-md.md, raw/github_doc-content-actions-concepts-security-secrets-md.md, raw/github_doc-content-actions-concepts-security-script-injections-md.md, raw/github_doc-content-actions-concepts-security-compromised-runners-md.md] --- # Actions Runners & Workflow Security ## Runners A **runner** is the machine that executes a [workflow](github-actions.md) job. - **GitHub-hosted runners** — ephemeral VMs GitHub provisions per job (Linux/Windows/macOS), pre-loaded with common tools, torn down after. Zero maintenance; **larger runners** offer more CPU/RAM/GPU and static IPs. - **Self-hosted runners** — your own machines (for special hardware, private network access, or cost). You manage the OS, security, and scaling; **runner groups** and **runner scale sets** (Actions Runner Controller on Kubernetes) handle fleets. Self-hosted runners on **public** repos are dangerous — a fork PR could run untrusted code on your infrastructure; GitHub-hosted ephemeral runners avoid this. ## Workflow security essentials - **`GITHUB_TOKEN`** — an automatically-created, short-lived token scoped to the running repo. Set least-privilege `permissions:` at workflow/job level; the default can be restricted org-wide. - **OIDC** — instead of long-lived cloud credentials in secrets, workflows can mint short-lived cloud tokens via OpenID Connect (`id-token: write`) — the recommended way to deploy to AWS/GCP/Azure. - **Secrets** — encrypted, masked in logs, scoped to repo/org/environment; never printed or passed to untrusted steps. - **Script injection** — never interpolate untrusted input (issue titles, PR bodies) directly into `run:` shells; pass via env vars and quote. A top real-world Actions vulnerability. - **Pin actions** — reference third-party actions by full commit SHA, not a moving tag, to prevent supply-chain tampering. These map to the wider [code-security](code-security.md) posture; deployment gating uses environments ([github-actions](github-actions.md)). --- title: "Authentication & Account Security" type: concept tags: [authentication, ssh, 2fa, passkey, pat] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-authentication-connecting-to-github-with-ssh-about-s.md, raw/github_doc-content-authentication-keeping-your-account-and-data-secure--2.md, raw/github_doc-content-authentication-authenticating-with-a-passkey-index-m.md, raw/github_doc-content-authentication-authenticating-with-single-sign-on-ab.md] --- # Authentication & Account Security ## Connecting to repositories - **SSH** — generate a key pair, add the public key to your account, and clone/push over `git@github.com:...`. SSH keys can require a passphrase; you can also sign commits with them. - **HTTPS + token** — clone over `https://github.com/...` and authenticate with a **personal access token** (not your password). The [GitHub CLI](github-cli.md) / Git Credential Manager store this for you. ## Account login security - **Two-factor authentication (2FA)** — required for contributors; supports authenticator apps (TOTP), security keys, and SMS (weakest). Save recovery codes. - **Passkeys** — passwordless sign-in bound to your device (WebAuthn); can satisfy both password and 2FA in one step. The modern recommended login. - **SSO** — organizations can require SAML/OIDC single sign-on; you authorize PATs/keys for SSO-protected orgs. ## Tokens (for automation) - **Fine-grained PATs** — scope to specific repos + minimal permissions, with expiry. Preferred. - **Classic PATs** — broad scopes; legacy. - **GitHub Apps** — installation tokens for integrations acting at scale; better than PATs for org automation ([rest-api](rest-api.md)). ## Commit signature verification Sign commits/tags (GPG, SSH, or S/MIME) so GitHub shows a **Verified** badge; branch protection can **require signed commits** ([branches-and-merging](branches-and-merging.md)). Securing the account is the first layer; scanning the code is [code-security](code-security.md). --- title: "Branches, Protection & Merging" type: concept tags: [branches, merge, branch-protection, default-branch] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-repositories-configuring-branches-and-merges-in-your-10.md, raw/github_doc-content-repositories-configuring-branches-and-merges-in-your-11.md, raw/github_doc-content-repositories-configuring-branches-and-merges-in-your.md, raw/github_doc-content-repositories-configuring-branches-and-merges-in-your-2.md, raw/github_doc-content-repositories-configuring-branches-and-merges-in-your-3.md, raw/github_doc-content-repositories-configuring-branches-and-merges-in-your-4.md] --- # Branches, Protection & Merging Branches let parallel work proceed without disturbing the **default branch** (usually `main`), which is what GitHub shows by default and treats as the base for new PRs. ## Merge methods When a [pull request](pull-requests.md) is approved, GitHub offers three ways to integrate it (each toggleable per repo): - **Merge commit** — keeps all commits and adds a merge commit (full history). - **Squash and merge** — combines the PR's commits into one on the base branch (clean linear history). - **Rebase and merge** — replays the PR's commits onto the base with no merge commit. ## Branch protection / rulesets Protected branches and **rulesets** enforce policy before code lands on important branches: - **Require pull request reviews** (N approvals, dismiss stale reviews, require code-owner review). - **Require status checks to pass** (CI from [Actions](github-actions.md) must be green). - **Require linear history / signed commits / up-to-date branches**. - **Restrict who can push** and block force-pushes/deletions. Rulesets are the newer, layerable evolution of classic branch protection, applying to multiple branches/tags by pattern. ## CODEOWNERS A `CODEOWNERS` file maps paths to owners who are **automatically requested for review** when those paths change — combine with "require code-owner review" protection to enforce domain review. This is the backbone of the [pull-request](pull-requests.md) review workflow on larger repos. --- title: "Code Security: Scanning, Dependabot, Secrets" type: concept tags: [code-security, code-scanning, codeql, dependabot, secret-scanning] updated: 2026-06-19 confidence: medium sources: [raw/github_doc-content-code-security-concepts-code-scanning-index-md.md, raw/github_doc-content-code-security-concepts-code-scanning-codeql-index-md.md] --- # Code Security: Scanning, Dependabot, Secrets GitHub's security suite (much of it free on public repos; "GitHub Advanced Security" on private/enterprise) defends three layers. ## Code scanning (SAST) **Code scanning** statically analyzes code for vulnerabilities and errors, surfacing results as **alerts** in the Security tab and inline on [pull requests](pull-requests.md). The default engine is **CodeQL** — GitHub's semantic analysis that treats code as a queryable database; you can run the standard query suites or write custom CodeQL queries. Third-party SARIF-producing scanners can upload results too. Run it via the default setup (one click) or a [workflow](github-actions.md). **Copilot Autofix** can suggest fixes for alerts. > The Dependabot and secret-scanning sections below summarize standard GitHub behavior; this KB mirrors the code-scanning/CodeQL docs, so treat those two sections as overview rather than source-cited detail. ## Dependabot (SCA) - **Dependabot alerts** — notify you when a dependency has a known vulnerability (from the GitHub Advisory Database). - **Dependabot security updates** — auto-open PRs bumping vulnerable dependencies to a fixed version. - **Dependabot version updates** — scheduled PRs keeping dependencies current via `dependabot.yml`. ## Secret scanning Detects committed **secrets** (API keys, tokens) across the repo's history and in pushes. **Push protection** blocks commits containing detected secrets before they land; partner patterns let providers auto-revoke leaked credentials. ## Putting it together Branch protection can require code-scanning/Dependabot checks to pass before merge ([branches-and-merging](branches-and-merging.md)); workflow-level hardening (least-privilege tokens, pinned actions) is in [actions-runners](actions-runners.md). Together these form the "shift-left" security posture: catch vulns in the PR, not in production. --- title: "Codespaces" type: concept tags: [codespaces, dev-environment, devcontainer, cloud] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-codespaces-about-codespaces-what-are-codespaces-md.md, raw/github_doc-content-codespaces-about-codespaces-deep-dive-md.md] --- # Codespaces A **codespace** is a cloud-hosted development environment — a full VS Code (browser or desktop) backed by a Docker container running on a cloud VM, created from a repository. ## How it works - Each codespace runs in a **Docker container** on a VM (choose machine size: cores/RAM/storage). - The default image is an Ubuntu Linux image with popular languages/tools pre-installed; you customize it per-project by committing a **dev container** configuration (`.devcontainer/devcontainer.json`). - Connect from the **browser**, **VS Code desktop**, or the **GitHub CLI** (`gh codespace`); you're dropped inside the container with the repo cloned. ## Dev containers `devcontainer.json` defines the image, features (toolchains), extensions, ports to forward, and post-create commands — so every contributor gets an identical, reproducible environment ("works on my machine" eliminated). The same dev container spec works locally in VS Code. ## Day-to-day - **Prebuilds** speed up creation by caching the configured environment. - **Port forwarding** exposes a running dev server with a shareable URL. - **Secrets** and dotfiles personalize environments without committing them. - Codespaces **stop** when idle and can be **deleted**; you're billed for compute + storage while they exist. Codespaces pairs naturally with [pull requests](pull-requests.md) (spin one up to review/run a PR) and is configured/used through [VS Code] tooling. --- title: "GitHub Actions (CI/CD)" type: concept tags: [actions, ci-cd, workflows, automation, yaml] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-actions-concepts-index-md.md, raw/github_doc-content-actions-concepts-workflows-and-actions-index-md.md, raw/github_doc-content-actions-concepts-workflows-and-actions-reusing-workf.md, raw/github_doc-content-actions-concepts-workflows-and-actions-contexts-md.md, raw/github_doc-content-actions-concepts-workflows-and-actions-expressions-m.md, raw/github_doc-content-actions-concepts-workflows-and-actions-variables-md.md, raw/github_doc-content-actions-concepts-workflows-and-actions-dependency-ca.md, raw/github_doc-content-actions-concepts-workflows-and-actions-deployment-en.md, raw/github_doc-content-actions-concepts-workflows-and-actions-concurrency-m.md, raw/github_doc-content-actions-concepts-workflows-and-actions-custom-action.md] --- # GitHub Actions (CI/CD) **GitHub Actions** runs automated **workflows** in response to repository events — the built-in CI/CD and automation engine. ## The object model - **Workflow** — a YAML file in `.github/workflows/` triggered by events (`on: push`, `pull_request`, `schedule`, `workflow_dispatch`, …). - **Job** — a set of steps that run on one [runner](actions-runners.md); jobs run in parallel by default and can declare `needs:` dependencies. - **Step** — a single task: either a shell command (`run:`) or an **action** (`uses:`). - **Action** — a reusable unit (from the Marketplace, a repo, or local) — itself just structured, packaged automation. ## Key building blocks - **Contexts & expressions** — `${{ github.sha }}`, `${{ secrets.X }}`, conditionals via `if:`. - **Secrets & variables** — encrypted secrets and plaintext variables at repo/org/environment scope. - **Environments** — deployment targets with protection rules (required reviewers, wait timers) and scoped secrets. - **Matrix** — run a job across many parameter combinations (OS × version). - **Caching & artifacts** — `dependency-cache` speeds builds; artifacts pass data between jobs/runs. - **Concurrency** — cancel or queue overlapping runs. ## Reusable workflows Rather than copy-pasting, define a **reusable workflow** that others call with `uses:`. This avoids duplication, centralizes maintenance, and lets teams build new pipelines from vetted building blocks. Composite actions similarly package repeated step sequences. Security of the token and secrets is critical — see [actions-runners](actions-runners.md) and [code-security](code-security.md). The full reference (syntax, contexts, expressions) is mapped in [docs-catalog](../summaries/docs-catalog.md). --- title: "GitHub CLI (gh)" type: concept tags: [gh, cli, command-line, automation] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-github-cli-github-cli-about-github-cli-md.md, raw/github_doc-content-github-cli-github-cli-creating-github-cli-extensions.md] --- # GitHub CLI (gh) **GitHub CLI** (`gh`) is the official open-source command-line tool for working with GitHub from your terminal — it complements `git` rather than replacing it. ## gh vs git - **`git`** works with the Git repository (commits, branches, push/pull) — local or any host. - **`gh`** works with *GitHub specifically* — PRs, issues, releases, Actions runs, gists, and the API — without context-switching to the browser. ## Common commands - `gh auth login` — authenticate (stores a token; also configures git credential helper). - `gh repo clone/create/fork/view`. - `gh pr create / list / checkout / review / merge` — the full [pull-request](pull-requests.md) loop from the terminal. - `gh issue create / list / close`. - `gh run list / view / watch` — inspect [Actions](github-actions.md) runs. - `gh api ` — raw [REST](rest-api.md)/[GraphQL](graphql-api.md) calls with auth + pagination handled. ## Scripting & extensions `gh` is built for automation: combine `gh api --paginate` with `--jq` to script against the API, and use it inside [Actions](github-actions.md) (pre-installed on hosted runners, authenticated via `GITHUB_TOKEN`). **Extensions** (`gh extension`) are installable subcommands — anyone can publish one as a repo, extending `gh` with custom workflows. This makes the CLI the most ergonomic surface for both interactive and automated GitHub work. --- title: "GitHub Packages" type: concept tags: [packages, registry, npm, container, artifacts] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-packages-learn-github-packages-introduction-to-githu.md, raw/github_doc-content-packages-index-md.md] --- # GitHub Packages **GitHub Packages** is a package-hosting service integrated with your repositories — publish, version, and consume packages alongside your code, with the same permissions model. ## Supported registries - **Container registry** — `ghcr.io` for Docker/OCI images (the recommended, most flexible registry; fine-grained per-image visibility). - **npm**, **NuGet**, **RubyGems**, **Maven/Gradle**, **Cargo** — language ecosystem registries. ## Key ideas - **Permissions** — packages can inherit a repo's access or be configured independently (especially container images, which support per-package visibility and granular roles). - **Authentication** — publish/install with a [PAT](rest-api.md), `GITHUB_TOKEN` in [Actions](github-actions.md), or a GitHub App token; configure your package manager to point at the GitHub registry endpoint. - **Publishing from CI** — the common pattern: an Actions workflow builds and pushes the package/image to `ghcr.io` on release, authenticated by the workflow's `GITHUB_TOKEN`. - **Linking to a repo** — connect a package to its source repo for provenance, shared visibility, and combined README/usage. ## When to use it Use Packages to keep build artifacts and code under one access model and audit trail. For public open-source libraries you may still prefer the canonical public registry (npmjs.com, crates.io); for private/internal artifacts and container images tied to GitHub auth, Packages is the natural home. --- title: "GitHub Pages" type: concept tags: [pages, static-site, hosting, custom-domain] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-pages-getting-started-with-github-pages-creating-a-g.md, raw/github_doc-content-pages-getting-started-with-github-pages-changing-the.md, raw/github_doc-content-pages-configuring-a-custom-domain-for-your-github-pa.md, raw/github_doc-content-pages-getting-started-with-github-pages-securing-you.md, raw/github_doc-content-pages-getting-started-with-github-pages-github-pages.md] --- # GitHub Pages **GitHub Pages** hosts static websites directly from a repository — docs, project sites, blogs, or personal sites, served over HTTPS for free. ## Site types & URLs - **User/Org site** — repo named `.github.io`, served at `https://.github.io`. - **Project site** — any repo, served at `https://.github.io/`. ## Publishing sources Two ways to build/deploy: 1. **Branch source** — Pages builds from a branch/folder (e.g. `main` `/docs`), optionally running **Jekyll** automatically. 2. **GitHub Actions source** — a [workflow](github-actions.md) builds the site (any generator — Next.js, Hugo, Astro, plain HTML) and deploys the artifact. This is the flexible modern path and isn't limited to Jekyll. ## Custom domains & HTTPS - Set a custom domain in Pages settings; add a `CNAME` (or `A`/`ALIAS`) DNS record and a `CNAME` file is committed to the repo. - **Enforce HTTPS** once the certificate provisions (GitHub issues it automatically via Let's Encrypt). ## Limits Pages is for **static** content — no server-side code or databases. There are soft size/bandwidth/build-frequency limits suited to docs and project sites. For dynamic apps you'd deploy elsewhere; for artifacts/registries see [github-packages](github-packages.md). --- title: "GraphQL API" type: concept tags: [graphql, api, queries, mutations] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-graphql-guides-introduction-to-graphql-md.md, raw/github_doc-content-graphql-guides-forming-calls-with-graphql-md.md] --- # GraphQL API GitHub's **GraphQL API** (v4) offers more precise and flexible queries than [REST](rest-api.md): you request exactly the fields you need in one round trip, instead of fetching whole resources across multiple endpoints. ## Core ideas - **Single endpoint** — all queries POST to `https://api.github.com/graphql`. - **Schema** — a strongly-typed graph (objects, fields, connections). The schema is introspectable, so tooling can autocomplete and validate queries. - **Queries** — read data; you specify the exact field tree, including nested relationships (a repo → its issues → their authors) in one call. - **Mutations** — write data (create issue, add comment, merge PR), passing an input object and selecting which fields to return. - **Pagination** — cursor-based via connections (`first:`/`after:`, `pageInfo { hasNextPage endCursor }`). ## Authentication Same tokens as REST — send `Authorization: Bearer ` ([rest-api](rest-api.md) for token types). Most schema fields require appropriate scopes/permissions. ## REST vs GraphQL - **GraphQL** — when you need many related pieces at once, want to minimize over-fetching, or need fields REST doesn't expose (Projects v2 automation is GraphQL-first). - **REST** — simpler, broader endpoint coverage, easier with plain `curl`/`gh api`. Use the **GraphQL Explorer** (interactive IDE) to build and test queries against the live schema. Rate limits are computed by query *complexity* (node count), not request count. --- title: "Issues & Projects" type: concept tags: [issues, projects, planning, labels, milestones] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-issues-index-md.md, raw/github_doc-content-issues-planning-and-tracking-with-projects-automatin.md, raw/github_doc-content-issues-planning-and-tracking-with-projects-creating-.md, raw/github_doc-content-issues-planning-and-tracking-with-projects-customizi.md, raw/github_doc-content-issues-planning-and-tracking-with-projects-automatin-2.md] --- # Issues & Projects ## Issues **Issues** track ideas, tasks, bugs, and feedback in a repository. Each issue has a title/body (Markdown), and can carry: - **Labels** — categorize (`bug`, `enhancement`); drive filtering and automation. - **Assignees** — who's responsible. - **Milestones** — group issues toward a release/deadline with progress tracking. - **Linked PRs** — a PR that says `Closes #N` auto-closes the issue on merge ([pull-requests](pull-requests.md)). - **Issue forms / templates** — standardize what reporters provide. - **Sub-issues / task lists** — break work down and track completion. ## Projects **Projects** is a flexible planning layer over issues and PRs — a customizable spreadsheet/board that pulls items from across repos: - **Views** — table, board (kanban), or roadmap; save and share per-view filters/sorts. - **Custom fields** — status, priority, iteration (sprints), estimates, dates. - **Built-in automation** — workflows that auto-add items, set status when a PR merges, or move cards on events; deeper automation via the [GraphQL API](graphql-api.md). ## How they fit together Issues capture *what* needs doing; Projects organize *when* and *by whom*. Both integrate with [pull requests](pull-requests.md) (linking, auto-close) and with [Actions](github-actions.md) for event-driven automation, giving a single planning-to-shipping trail. --- title: "Pull Requests" type: concept tags: [pull-requests, code-review, merge, collaboration] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-pull-requests-collaborating-with-pull-requests-getti-2.md, raw/github_doc-content-pull-requests-collaborating-with-pull-requests-addre.md] --- # Pull Requests A **pull request (PR)** proposes merging the commits on one branch into another and is the unit of code review on GitHub — you're asking your team to review changes and provide feedback before they land. ## Lifecycle 1. **Open** a PR from your branch (or fork) against a base branch; describe what changed and why. 2. **Review** — reviewers comment line-by-line, request changes, or approve. CODEOWNERS may be auto-requested ([branches-and-merging](branches-and-merging.md)). 3. **Checks** — required status checks ([Actions](github-actions.md)) must pass. 4. **Address feedback** — push more commits; the PR updates in place. Conversations can be resolved. 5. **Merge** — once approvals + checks satisfy branch protection, merge (merge commit / squash / rebase). ## Best practices (from the docs) - **Small, focused PRs** that serve a single purpose — faster to review, fewer bugs, easier to revert. - **Clear context** in the description so reviewers see *what* changed and *why* — link the issue it closes (`Closes #123` auto-closes on merge). - **Draft PRs** for work-in-progress that isn't ready for review. ## Useful features - **Suggested changes** — reviewers propose exact edits the author can commit with one click. - **Auto-merge** — merges automatically once all requirements pass. - **Linked issues** — connect PRs to [Issues](issues-and-projects.md) for traceability. PRs are also the contribution mechanism across forks in open source ([repositories-and-git](repositories-and-git.md)). --- title: "Repositories & Git Workflow" type: concept tags: [repositories, git, clone, commit, files] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-repositories-archiving-a-github-repository-about-arc.md, raw/github_doc-content-get-started-start-your-journey-about-github-and-git-.md] --- # Repositories & Git Workflow A **repository** ("repo") is the unit of project storage on GitHub: it holds your files, full Git history, branches, issues, pull requests, and settings. Repos can be **public** (visible to all) or **private** (access-controlled). ## The basic Git loop 1. **Clone** the remote repo (`git clone `) — HTTPS or SSH ([authentication](authentication.md)). 2. **Branch** (`git checkout -b feature`) to isolate work ([branches-and-merging](branches-and-merging.md)). 3. **Commit** changes locally (`git add` / `git commit`). 4. **Push** the branch to GitHub (`git push`). 5. Open a [pull request](pull-requests.md) to merge it back. ## Repository contents & settings - **Files** — edit in the browser, locally, or in [Codespaces](codespaces.md); GitHub renders `README.md` on the repo home. - **Settings** — visibility, collaborators/teams, default branch, branch protection, and feature toggles (Issues, Projects, Pages, Discussions). - **Releases & tags** — package a point in history with notes and binaries. - **Archiving** — a repo can be made read-only ("archived") when no longer maintained; it stays visible but blocks new commits/issues/PRs. ## Forks vs branches A **branch** is a parallel line of work *inside* a repo. A **fork** is a full copy of a repo *under your own account* — the basis of the open-source contribution model: fork → branch → PR back to the upstream repo ([pull-requests](pull-requests.md)). Repository configuration of merges/branches: [branches-and-merging](branches-and-merging.md). --- title: "REST API" type: concept tags: [rest, api, automation, authentication, pagination] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-rest-about-the-rest-api-about-the-rest-api-md.md, raw/github_doc-content-rest-authentication-authenticating-to-the-rest-api-m.md, raw/github_doc-content-rest-about-the-rest-api-index-md.md, raw/github_doc-content-rest-about-the-rest-api-api-versions-md.md, raw/github_doc-content-rest-about-the-rest-api-breaking-changes-md.md, raw/github_doc-content-rest-guides-building-a-ci-server-md.md] --- # REST API GitHub's **REST API** lets you build scripts and apps that automate processes, integrate with GitHub, and extend it — endpoints are documented per resource (repos, issues, pull requests, actions, etc.). ## Authentication Every authenticated request sends a token in the `Authorization: Bearer ` header. Token options: - **Fine-grained personal access tokens (PATs)** — scoped to specific repos and permissions; preferred over classic PATs. - **Classic PATs** — broad scopes; legacy. - **GitHub App installation tokens** — for apps acting on installations (best for integrations at scale). - **`GITHUB_TOKEN`** inside [Actions](actions-runners.md). ## Working with the API - **Versioning** — pin `X-GitHub-Api-Version`; breaking changes ship under new dated versions. - **Pagination** — list endpoints page via `?per_page=&page=`; follow the `Link` header's `rel="next"` rather than guessing. - **Rate limits** — primary (e.g. 5,000 req/hr authenticated) and secondary (anti-abuse) limits; watch `X-RateLimit-Remaining` and back off on `403`/`429`. - **Conditional requests** — `ETag`/`If-None-Match` return `304` and don't count against the limit. - **Media types** — request raw/HTML/diff representations via `Accept`. ## Tooling The [GitHub CLI](github-cli.md) (`gh api`) and Octokit SDKs wrap the REST API with auth, pagination, and retries handled. For more precise/flexible queries, consider the [GraphQL API](graphql-api.md). The per-resource endpoint reference is catalogued in [docs-catalog](../summaries/docs-catalog.md). --- title: "Webhooks" type: concept tags: [webhooks, events, integrations, automation] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-webhooks-about-webhooks-md.md, raw/github_doc-content-webhooks-index-md.md, raw/github_doc-content-webhooks-types-of-webhooks-md.md, raw/github_doc-content-webhooks-testing-and-troubleshooting-webhooks-index-.md, raw/github_doc-content-webhooks-using-webhooks-automatically-redelivering-f.md] --- # Webhooks **Webhooks** let GitHub notify an external service when events happen in a repository, organization, or app — the push-based counterpart to polling the [REST API](rest-api.md). ## How they work 1. You register a webhook with a **payload URL**, a **content type** (`application/json`), the **events** to subscribe to (`push`, `pull_request`, `issues`, `release`, …, or "everything"), and an optional **secret**. 2. When a subscribed event fires, GitHub sends an HTTP **POST** to your URL with a JSON payload describing what happened, plus headers (`X-GitHub-Event`, `X-GitHub-Delivery`). 3. Your server responds quickly (2xx) and processes asynchronously. ## Security - **Validate the signature.** With a secret configured, GitHub signs each delivery (`X-Hub-Signature-256`, HMAC-SHA256). Verify it before trusting the payload — otherwise anyone who learns your URL can forge events. - Treat payloads as untrusted input; scope what the handler can do. ## Scope & alternatives - **Repository/org webhooks** — configured in settings; good for one project or org. - **GitHub App webhooks** — an app receives events across all installations, the scalable path for integrations. - **Reliability** — GitHub records each delivery; you can inspect payloads/responses and **redeliver** failed ones for debugging. For event-driven automation *inside* GitHub (rather than to an external server), [Actions](github-actions.md) triggered `on:` events is usually simpler; use webhooks when an outside system needs to react. --- title: "What is GitHub" type: concept tags: [github, git, overview, platform] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-get-started-start-your-journey-about-github-and-git-.md] --- # What is GitHub **GitHub** is a developer platform for building, shipping, and maintaining software. At its core it provides cloud-hosted **Git** repositories, plus a layer of collaboration and automation on top: - **Git hosting** — remote repositories for version-controlled code ([repositories-and-git](repositories-and-git.md)). - **Code review** — [pull requests](pull-requests.md) for proposing and reviewing changes. - **Project management** — [Issues and Projects](issues-and-projects.md) for planning and tracking work. - **CI/CD & automation** — [GitHub Actions](github-actions.md) runs workflows on repository events. - **APIs** — [REST](rest-api.md) and [GraphQL](graphql-api.md) for integration and automation, plus the [GitHub CLI](github-cli.md). - **Hosting** — [Pages](github-pages.md) (static sites), [Packages](github-packages.md) (artifacts), [Codespaces](codespaces.md) (cloud dev environments). - **Security** — [authentication](authentication.md) and [code security](code-security.md) (code scanning, Dependabot, secret scanning). ## Git vs GitHub **Git** is the distributed version-control system that runs locally and tracks history. **GitHub** is a hosting and collaboration service built around Git — it stores the remote repository and adds the web UI, review, automation, and access control Git itself doesn't provide. You can use Git without GitHub, but GitHub always speaks Git. ## Plans and editions GitHub offers free and paid plans (Free, Team, Enterprise) plus GitHub Enterprise Server (self-hosted). Most features in this wiki are available on Free/Pro/Team (`fpt` in the docs); enterprise-only behavior is out of scope here. The full area map is in [docs-catalog](../summaries/docs-catalog.md). --- title: "Activity Log" type: log --- # Activity Log Append-only record of all wiki changes. ## Format Each entry follows this format: ``` ### YYYY-MM-DD HH:MM — [Action Type] - **Source/Trigger**: what initiated the action - **Pages created**: list of new pages - **Pages updated**: list of updated pages - **Notes**: any contradictions flagged, decisions made ``` --- ### 2026-04-08 00:00 — Setup - **Source/Trigger**: Repository initialized - **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md - **Pages updated**: none - **Notes**: Empty knowledge base ready for first source ingestion ### 2026-06-19 00:00 — Initial curation (medium rung) - **Source/Trigger**: github/docs content/ (open-source docs); two gather passes (see note) - **Pages created**: 16 concepts, 1 summary (docs-catalog), 1 synthesis (ci-cd-pipeline) - **Pages updated**: index.md - **Notes**: First gather combined dirs per fetcher and alphabetical capping STARVED repositories/pull-requests/issues/pages/packages/webhooks (0 files). Fixed: one fetcher PER content dir; re-gather filled them (raw/ = union, 295 files). actions get-started/tutorials also starved under concepts within the actions fetcher — concepts/ is the meatiest content so accepted. Enterprise/Copilot/billing excluded by design. --- title: "Docs Catalog" type: summary tags: [catalog, map, reference] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-actions-concepts-index-md.md, raw/github_doc-content-rest-about-the-rest-api-about-the-rest-api-md.md] --- # Docs Catalog Map of the github/docs corpus this wiki distills (content/ areas mirrored in `raw/` as `github_doc-content-.md`). Use it to find the right raw source; the wiki covers the high-traffic concepts. | Area | Raw prefix | Wiki coverage | |---|---|---| | Get started | `get-started-*` | [what-is-github](../concepts/what-is-github.md) | | Repositories | `repositories-*` | [repositories-and-git](../concepts/repositories-and-git.md), [branches-and-merging](../concepts/branches-and-merging.md) | | Pull requests | `pull-requests-*` | [pull-requests](../concepts/pull-requests.md) | | Issues & Projects | `issues-*` | [issues-and-projects](../concepts/issues-and-projects.md) | | Actions | `actions-concepts-*` | [github-actions](../concepts/github-actions.md), [actions-runners](../concepts/actions-runners.md) | | GitHub CLI | `github-cli-*` | [github-cli](../concepts/github-cli.md) | | REST API | `rest-*` | [rest-api](../concepts/rest-api.md) | | GraphQL API | `graphql-*` | [graphql-api](../concepts/graphql-api.md) | | Pages | `pages-*` | [github-pages](../concepts/github-pages.md) | | Packages | `packages-*` | [github-packages](../concepts/github-packages.md) | | Codespaces | `codespaces-*` | [codespaces](../concepts/codespaces.md) | | Authentication | `authentication-*` | [authentication](../concepts/authentication.md) | | Code security | `code-security-concepts-*` | [code-security](../concepts/code-security.md) | | Webhooks | `webhooks-*` | [webhooks](../concepts/webhooks.md) | ## Reference spaces NOT ingested (look them up live) - **REST endpoint reference** — one page per resource (`/rest/`); use [`gh api`](../concepts/github-cli.md) or the docs site for exact endpoints/params. - **Actions reference** — full workflow YAML syntax, contexts, expressions, and the runner-images tool lists (`actions/reference`). - **Workflow commands & built-in actions** — `actions/checkout`, `setup-node`, etc. live on the Marketplace. - **CodeQL query reference** — per-language query packs. ## Scope note This wiki targets GitHub.com Free/Pro/Team developer features. **Enterprise/admin, billing, Copilot, education, and sponsors** areas were intentionally excluded from the gather and are out of scope — use the docs site for those. --- title: "End-to-End: From Commit to Deploy" type: synthesis tags: [ci-cd, workflow, pull-request, deployment, synthesis] updated: 2026-06-19 confidence: high sources: [raw/github_doc-content-pull-requests-collaborating-with-pull-requests-getti-2.md, raw/github_doc-content-actions-concepts-workflows-and-actions-index-md.md, raw/github_doc-content-repositories-configuring-branches-and-merges-in-your-10.md, raw/github_doc-content-actions-concepts-security-github-token-md.md] --- # End-to-End: From Commit to Deploy How GitHub's features compose into one shipping pipeline — the path most teams actually run. ## 1. Branch and commit Create a feature branch off the protected default branch ([repositories-and-git](../concepts/repositories-and-git.md)), commit, and push. Signed commits earn a Verified badge ([authentication](../concepts/authentication.md)). ## 2. Open a pull request The PR is the review and gate point ([pull-requests](../concepts/pull-requests.md)). Keep it small and link the issue (`Closes #N`) for traceability to [Projects](../concepts/issues-and-projects.md). ## 3. Automated checks run Opening/updating the PR triggers [Actions](../concepts/github-actions.md) workflows (`on: pull_request`): lint, test, build, and **code scanning** ([code-security](../concepts/code-security.md)). Jobs run on [runners](../concepts/actions-runners.md) with a least-privilege `GITHUB_TOKEN`. ## 4. Review gate [Branch protection / rulesets](../concepts/branches-and-merging.md) hold the merge until: required approvals (incl. CODEOWNERS), all required status checks green, branch up to date, and Dependabot/secret-scanning clean. This is where quality is enforced, not by convention. ## 5. Merge Squash/merge/rebase per repo policy. The merge to the default branch is itself an event. ## 6. Deploy A `on: push` (to `main`) or `on: release` workflow builds and deploys. Use **environments** for protection rules (required reviewers, wait timers) and scoped secrets, and prefer **OIDC** over stored cloud credentials ([actions-runners](../concepts/actions-runners.md)). Targets might be [Pages](../concepts/github-pages.md) (static), [Packages/`ghcr.io`](../concepts/github-packages.md) (images), or external clouds. ## The compounding effect Each layer is optional alone but compounding together: PRs catch logic errors, required checks catch regressions, code scanning catches vulns, environments gate prod, and OIDC removes long-lived secrets. The same events also drive [webhooks](../concepts/webhooks.md) and the [APIs](../concepts/rest-api.md) for anything GitHub doesn't do natively.