diff --git a/README.md b/README.md index c9a7c4c..3f7f719 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,14 @@ That means the compatibility target is not "GitHub-like". It is GitHub: ## Status -Usable today, and honest about the edges. The compatibility surface is built and released: three tagged versions are out, and one tag push produces the prebuilt binaries, the Linux packages, and the container image attached to each release (see [Install](#install)). +Usable today, and honest about the edges. The compatibility surface is built and released: four tagged versions are out, and one tag push produces the prebuilt binaries, the Linux packages, and the container image attached to each release (see [Install](#install)). | Version | What it added | | --- | --- | | `v0.1.0` | The first complete forge: auth, git read and push, issues, pull requests, code review, webhooks, events, search, conditional requests, the full REST and GraphQL surface | | `v0.1.1` | A performance pass: batch loaders instead of N+1, keyset pagination, FTS-backed search, object caches, GraphQL dataloaders | | `v0.1.2` | The release pipeline: archives, deb/rpm/apk, a multi-arch container image, and the language-agnostic package managers | +| `v0.1.3` | The built-in web UI (repo and code browsing, diffs, inline review, profiles, settings, notifications), a conformance suite wired into CI, the REST and GraphQL compatibility ladders, h2c serving, and a green Postgres test leg | What works, end to end: @@ -34,7 +35,7 @@ Not yet: - SSH git transport (the config is reserved, the server is not wired) - Organization accounts (everything is user-owned for now) - At-rest encryption of webhook secrets -- GitHub Actions runner compatibility +- GitHub Actions runner compatibility (in progress in the separate `tamnd/githome-action` project, not yet served by this binary) The definition of done is mechanical, not a claim. Every endpoint has a recorded fixture and a contract test; real `gh` and real `git` drive the server in CI; a JSON differ compares responses against recorded github.com output field for field; and the suite runs against both SQLite and Postgres. The `githome-conform` tool certifies a running instance against the compatibility matrix as a black-box client and exits non-zero on any drift, so it can gate a release. diff --git a/docs/content/deploy/docker.md b/docs/content/deploy/docker.md index e912a2f..bd06e06 100644 --- a/docs/content/deploy/docker.md +++ b/docs/content/deploy/docker.md @@ -11,7 +11,7 @@ Create `docker-compose.yml`: ```yaml services: githome: - image: ghcr.io/tamnd/githome:0.1.2 # pin to a release tag + image: ghcr.io/tamnd/githome:0.1.3 # pin to a release tag restart: unless-stopped ports: - "127.0.0.1:3000:3000" # loopback only; nginx/Caddy handles TLS @@ -47,7 +47,7 @@ Add a Postgres service and change the database URL: ```yaml services: githome: - image: ghcr.io/tamnd/githome:0.1.2 + image: ghcr.io/tamnd/githome:0.1.3 restart: unless-stopped ports: - "127.0.0.1:3000:3000" diff --git a/docs/content/getting-started/connect-your-tools.md b/docs/content/getting-started/connect-your-tools.md index 6fc8d10..c077545 100644 --- a/docs/content/getting-started/connect-your-tools.md +++ b/docs/content/getting-started/connect-your-tools.md @@ -87,12 +87,8 @@ All standard `github_*` resources and data sources work against githome. ## GitHub Actions runners -Use [tamnd/githome-action](https://github.com/tamnd/githome-action) to run -GitHub Actions workflows against githome. The runner speaks the same Actions -protocol as GitHub's hosted runners. - -```sh -./githome-action --url https://your-githome-host --token RUNNER_TOKEN -``` - -Register it from your repo: **Settings > Actions > Runners > Add runner**. +GitHub Actions support is in progress in the separate +[tamnd/githome-action](https://github.com/tamnd/githome-action) project, which +reimplements the Actions runner and service protocol. The githome binary does +not serve the Actions API yet, so workflows do not run against a githome host +today. Follow that repository for status. diff --git a/docs/content/getting-started/installation.md b/docs/content/getting-started/installation.md index 1143d95..08b8cc5 100644 --- a/docs/content/getting-started/installation.md +++ b/docs/content/getting-started/installation.md @@ -9,13 +9,19 @@ weight: 30 Grab the latest release from [GitHub Releases](https://github.com/tamnd/githome/releases/latest). +Archive names carry the version, so set it once and download the right asset. +Each archive holds all three binaries (`githome`, `githome-migrate`, +`githome-conform`) plus the license and readme. + ```sh +VERSION=0.1.3 + # Linux amd64 -curl -L https://github.com/tamnd/githome/releases/latest/download/githome_linux_amd64.tar.gz | tar xz +curl -L https://github.com/tamnd/githome/releases/download/v${VERSION}/githome_${VERSION}_linux_amd64.tar.gz | tar xz sudo mv githome /usr/local/bin/ # macOS arm64 (Apple Silicon) -curl -L https://github.com/tamnd/githome/releases/latest/download/githome_darwin_arm64.tar.gz | tar xz +curl -L https://github.com/tamnd/githome/releases/download/v${VERSION}/githome_${VERSION}_darwin_arm64.tar.gz | tar xz sudo mv githome /usr/local/bin/ ``` @@ -60,7 +66,7 @@ apk add --allow-untrusted githome_*.apk go install github.com/tamnd/githome/cmd/githome@latest ``` -Requires Go 1.22+. +Requires Go 1.26+ and a `git` binary on `PATH`. ## Requirements diff --git a/docs/content/getting-started/introduction.md b/docs/content/getting-started/introduction.md index 67785c6..68a3bd5 100644 --- a/docs/content/getting-started/introduction.md +++ b/docs/content/getting-started/introduction.md @@ -42,7 +42,7 @@ keep everything else: - VS Code and JetBrains git integrations: no change needed - Octokit (JS, Python, Go, Ruby): set `baseUrl` once - Terraform GitHub provider: set `base_url` in the provider block -- CI runners: use tamnd/githome-action for GitHub Actions compatibility +- CI runners: GitHub Actions support is in progress in tamnd/githome-action (not yet served by the githome binary) See [Connect your tools](/getting-started/connect-your-tools/) for the exact config change for each tool. diff --git a/docs/content/getting-started/quick-start.md b/docs/content/getting-started/quick-start.md index f883268..b65b713 100644 --- a/docs/content/getting-started/quick-start.md +++ b/docs/content/getting-started/quick-start.md @@ -28,8 +28,9 @@ If you prefer a binary: ```sh # macOS (Apple Silicon) -curl -L https://github.com/tamnd/githome/releases/latest/download/githome_darwin_arm64.tar.gz | tar xz -./githome serve +VERSION=0.1.3 +curl -L https://github.com/tamnd/githome/releases/download/v${VERSION}/githome_${VERSION}_darwin_arm64.tar.gz | tar xz +GITHOME_HTML_BASE_URL=http://localhost:3000 ./githome ``` ## Create your first account diff --git a/docs/content/reference/github-compatibility.md b/docs/content/reference/github-compatibility.md index 6293589..bfe05cc 100644 --- a/docs/content/reference/github-compatibility.md +++ b/docs/content/reference/github-compatibility.md @@ -20,7 +20,6 @@ the host changes. | Terraform github provider | `base_url = "https://your-host/"` | | VS Code (git) | No change needed | | JetBrains (git) | No change needed | -| GitHub Actions runners | Use tamnd/githome-action | ## Supported features @@ -43,13 +42,16 @@ the host changes. | GraphQL v4 (queries, mutations, relay pagination) | Supported | | Git Smart HTTP (clone, fetch, push) | Supported | | Check runs and status contexts | Supported | -| GitHub Actions (CI workflows) | Supported via tamnd/githome-action | +| Web notifications inbox | Supported | ## Not supported | Feature | Notes | |---|---| -| SSH transport | Planned | +| SSH transport | Planned (config reserved, not yet wired) | +| Organization accounts | Planned (everything is user-owned today) | +| GitHub Actions (CI workflows) | In progress in the separate tamnd/githome-action project; not yet served by the githome binary | +| Email notifications | Not planned (the web inbox is supported) | | GitHub Packages / Container Registry | Not planned | | GitHub Copilot | Not applicable | | Dependabot | Not planned | @@ -58,4 +60,3 @@ the host changes. | Code scanning / SARIF | Not planned | | SAML SSO | Not planned | | Merge queue | Not planned | -| Notifications (email / web) | Not planned | diff --git a/releases/v0.1.3.md b/releases/v0.1.3.md new file mode 100644 index 0000000..60efbb1 --- /dev/null +++ b/releases/v0.1.3.md @@ -0,0 +1,131 @@ +Githome v0.1.3 is the release where the server grows a face. v0.1.0 shipped the +REST and GraphQL forge, v0.1.1 made it fast, and v0.1.2 turned a tag into every +downloadable artifact. This release adds the built-in web UI that those notes +never mentioned, hardens the API against real `gh` traffic with a conformance +suite wired into CI, and fills a long list of compatibility gaps. The API +contract from v0.1.1 is unchanged, so existing clients keep working; everything +here is additive. + +## The web UI + +The biggest change is a server-rendered web interface, served from the same +binary and on by default. It is a reimplemented Primer look, plain +`html/template` with htmx for the interactive bits and a handful of web +components, and the write paths work with JavaScript disabled. No React, no +build step, no second process. + +**Browsing.** Repository home, the file tree, blob view with syntax +highlighting, rendered Markdown, the commit log, a single-commit view, and +blame that annotates each line with the commit that introduced it. Code lines +are selectable and permalink with `#L3-L7` anchors, and short-SHA and numeric +permalinks canonicalize to their full form. + +**Pull requests and review.** The conversation, the commits, and a Files tab +that renders the diff unified or side-by-side, highlights word-level changes +inside an edited line, and expands hunk context on demand. The diff display +choice rides a query parameter so a link carries the reader's view. + +**Issues and the rest.** Issue threads with milestone resolution and paging for +long conversations, labels and locks and list filters, a dashboard, a checks +tab, a notifications inbox backed by the domain layer, user profiles with stars, +followers, and following tabs, a repository Settings tab for owners, and the +account settings tree. The whole thing scales down to a phone with a real +breakpoint scale and touch targets. + +**Auth and browse mode.** Sign in, sign up, and sign out in the browser, `gh +auth login` working end to end through the web flow, and a `githome browse` +subcommand that serves a local repository read-only with no sign-in for +zero-config viewing. + +## Compatibility, certified in CI + +The definition of done stopped being a claim. `githome-conform` certifies a +running instance against the compatibility matrix as a black-box client and +exits non-zero on any drift, and that conformance run is now wired into CI +alongside contract tests that replay the literal GraphQL documents `gh` sends. + +**GraphQL.** The surface now validates the documents the `gh` CLI actually +emits. Query cost is priced by GitHub's node-count model rather than a fixed +point cap, so a large-but-bounded query passes where it used to be rejected. +Rate-limit headers, `X-RateLimit` accounting that refunds on a 304, honest +errors instead of silently dropped or faked mutations, the write-side mutations +`gh` sends, commit data fields, `mergeCommit` and `closingIssuesReferences`, +the `license`, `codeOfConduct`, and meta root queries, and a long list of +filled Issue, Label, User, and Repository fields. + +**REST.** The P0 and P1 compatibility ladders: the merge check, the root +document, contents `sha`, branch protection, notifications, pagination, checks, +refs, releases, gists, org membership and webhooks, search, the event-feed +polling contract, branch merge, `repository_dispatch`, lookup-by-id, the +`text-match` media type on search, a real collaborator surface that honors +roles for repository write access, global repository listing, the community +profile, CODEOWNERS errors, and a webhook test endpoint. + +**Releases, gists, and apps.** A full Releases API with asset upload at +`/api/uploads/`, full Gist CRUD with stars, forks, and comments, and the OAuth +web flow, device flow, and GitHub Apps endpoints. + +## Performance and serving + +The second rung of the performance ladder takes the read path off its worst +hotspots, brings page renders inside the budget, trims per-render allocations +on the hot template path, pools the render buffer, and streams assets instead +of buffering them. The server also speaks HTTP/2 cleartext (h2c). + +## Storage correctness + +The Postgres leg of the test matrix is now green and stays that way. A drift +guard asserts the consolidated `schema.pg.sql` matches a full migration replay, +the rollback of the GitHub Apps migration drops its foreign-key columns in the +right order, and code search matches paths and orders results the same way on +Postgres as on SQLite. The suite runs against both SQLite and Postgres on every +push. + +## Upgrading from v0.1.2 + +The HTTP and GraphQL contract is unchanged. Migrations run automatically on +startup (or `githome-migrate up` if you run them yourself), so the upgrade is a +drop-in. The web UI is on by default; set `GITHOME_WEB_ENABLED=false` to serve +the APIs and git transport only. + +## Install + +See [INSTALL.md](https://github.com/tamnd/githome/blob/main/INSTALL.md) for every +method. The common paths: + +```sh +brew install tamnd/tap/githome # macOS +docker pull ghcr.io/tamnd/githome:0.1.3 # container +go install github.com/tamnd/githome/cmd/githome@v0.1.3 # from source +``` + +Or download an archive and verify it: + +```sh +tar -xzf githome_0.1.3_linux_amd64.tar.gz +sha256sum -c checksums.txt +sudo install githome/githome /usr/local/bin/ +``` + +## Platform support + +Binaries are static (no libc dependency, no cgo) and built from a single +toolchain: + +| OS | Architectures | +|---------|--------------------------------------------| +| Linux | amd64, arm64, arm, 386, ppc64le, s390x, riscv64 | +| macOS | amd64, arm64 | +| Windows | amd64, arm64, 386 | +| FreeBSD | amd64, arm64 | +| OpenBSD | amd64, arm64 | + +## Known gaps + +Unchanged from v0.1.2: + +- SSH git transport (the config is reserved, the server is not wired) +- Organization accounts (everything is user-owned for now) +- At-rest encryption of webhook secrets +- GitHub Actions runner compatibility (in progress in the separate + tamnd/githome-action project, not yet served by the githome binary)