Apache Magpie — Website

Landing page and documentation hub for Apache Magpie, an AI assistant that helps open-source maintainers handle the repetitive parts of running a project — triage, mentoring, drafting fixes, and security-report handling — so they can focus on the work that needs a human.

Status: Apache Top-Level Project. Project source lives at apache/magpie; this repo holds the public website.

Stack

Layer	Tool
Framework	Astro 7 (static output)
UI	React 19 + Tailwind CSS 4
Interaction	React state, native controls and CSS transitions; reduced-motion support
Icons	lucide-react + inline SVG for brand marks
Docs	Astro content collections, markdown synced from apache/magpie/docs

Zero runtime dependency on closed-source design tooling. All components are owned in-tree.

Local development

npm install
npm run sync-docs    # one-time fetch of markdown from apache/magpie
npm run dev          # http://localhost:4321

Always start the dev server with npm run dev — it runs scripts/dev.sh, which sets ASTRO_TELEMETRY_DISABLED=1 before launching astro dev. Without that, Astro tries to write to its telemetry config dir (e.g. ~/Library/Preferences/astro) and the dev server fails to start in sandboxed environments. Pass extra flags through, e.g. npm run dev -- --port 3000.

The prebuild hook runs sync-docs automatically, so npm run build always pulls a fresh copy of docs before generating the static site.

Available commands

Command	Purpose
npm run dev	Dev server with HMR (telemetry disabled via scripts/dev.sh)
npm run sync-docs	Clone apache/magpie (sparse, docs/ + images/) into src/content/docs/ and public/docs-assets/
npm run build	Static build to dist/ (runs sync-docs first)
npm run preview	Serve the built site locally
npm run astro	Astro CLI passthrough
npm run check:fast	Knip, authored CSS audit, type checking, unit and negative checker tests
npm run test:browser	Force-build, HTML/link/asset/route audit, responsive/a11y/interaction tests
npm run check	Complete blocking gate
npm run hooks:verify	Prove Git dispatches both installed hooks and rejects a failing probe

Install local hooks with prek 0.3.6 or newer:

prek install --overwrite --git-dir "$(git rev-parse --git-common-dir)" --hook-type pre-commit --hook-type pre-push
npm run hooks:verify

Pre-commit runs hygiene and the fast gate; pre-push runs the complete gate. A global core.hooksPath must forward to this repository's hooks. The verification command exercises the effective path in a temporary repository and fails when dispatch is missing; it never stages, stashes, commits or pushes this project. See the consistency contract for exact assertions, fixtures and boundaries.

Environment variables (optional)

Var	Default	Purpose
MAGPIE_DOCS_REPO	https://github.com/apache/magpie.git	Source repo for markdown
MAGPIE_DOCS_BRANCH	main	Branch to sync from

Project structure

website/
├── scripts/
│   └── sync-docs.sh             # sparse-clone docs/ + images/ from source repo
├── src/
│   ├── components/
│   │   ├── landing/             # LP + SiteHeader/SiteFooter
│   │   ├── docs/                # tree + search dialog
│   │   └── stories/             # illustrative trend + interactive data charts
│   ├── content/
│   │   └── docs/                # synced markdown (gitignored)
│   ├── content.config.ts        # docs collection schema
│   ├── layouts/
│   │   ├── BaseLayout.astro
│   │   └── DocsLayout.astro
│   ├── lib/utils.ts             # deployment base-path helper
│   ├── pages/
│   │   ├── index.astro          # /
│   │   └── docs/
│   │       ├── index.astro      # /docs
│   │       └── [...slug].astro  # /docs/<any>
│   └── styles/                  # spacing, shared chrome, page layouts, dark tokens
├── tests/browser/               # discovered routes, interactions, broken fixtures
├── public/                       # static assets (logos, favicons, /docs-assets)
└── astro.config.mjs

Docs pipeline

The website is decoupled from the docs source. The markdown lives in apache/magpie/docs; this repo fetches it at build time and renders it through Astro content collections.

apache/magpie/docs/*.md
        │
        ▼  scripts/sync-docs.sh (sparse clone)
src/content/docs/*.md
        │
        ▼  Astro content collection
dist/docs/**/*.html   (one static page per markdown file)

Image references inside markdown (../../images/foo.png) are rewritten to /docs-assets/foo.png during sync so they resolve against public/docs-assets/.

CI

The existing Build and Deploy workflow runs the hygiene and static gates, then fresh-build browser checks and the development preview tests. Production builds and publication depend on those checks. PR source-annotation previews and their Astro/Jekyll adapter tests remain part of the upstream workflow.

Deployment

The site is published by ASF infrastructure, not GitHub Pages. On every push to main, CI builds the static site and force-pushes dist/ (an orphan, single-commit history) to the publish branch. The root .asf.yaml — carried into that branch — tells ASF infra to serve it:

publish:
  whoami: publish

ASF infra serves the publish branch at the project's inferred hostname — magpie-site → magpie.apache.org (served at the apex root). The hostname must not be set explicitly via a hostname: field; asfyaml forbids naming your own $project.apache.org ("it has to be inferred to prevent abuse"), and doing so stops the site from publishing.

The site is built with base: '/' so all links and assets resolve against the apex domain. Set SITE_BASE / SITE_URL to preview under a subpath (e.g. GitHub Pages).

One-time infra setup (outside this repo): for a brand-new project, ASF Infra may still need to provision DNS/TLS for magpie.apache.org before the inferred hostname resolves.

Previewing a pull request

A committer can publish a live preview of any open pull request by commenting:

/show-preview

The Publish PR previews workflow runs on a 15-minute schedule and then tracks the PR's head commit — each new push is picked up on the next run — though GitHub may delay a scheduled run when it is busy. It appears at https://magpie-pr<N>.staged.apache.org/, and like the production site, ASF staging takes a few minutes to propagate after each publish. A maintainer who does not want to wait can dispatch the Publish PR previews workflow manually with the PR number.

Previews are retired when the PR closes: the site is replaced with a notice rather than disappearing, because deleting the branch does not unstage the site — the branch is only deleted (as a separate, later step) once the notice is live.

To turn a preview off before the PR closes, delete the /show-preview comment (and, if the preview was started by manual dispatch, also delete the bot's arming comment); the next scheduled run retires it.

Agent-assisted contribution (apache-magpie)

This repo adopts the apache/magpie framework via a snapshot mechanism, making its maintainer-facing agent skills available in harnesses such as Claude Code.

The framework is not vendored — it lives as a gitignored snapshot under .apache-magpie/, fetched on demand from the version pinned in the committed .apache-magpie.lock. The only framework artefact committed to this repo is the setup skill at .agents/skills/magpie-setup/; everything else is a gitignored symlink the setup skill wires up.

This site currently wires the framework's always-on setup-* (secure-agent setup, status, upstream-fix) and list-* (skill discovery) families. The opt-in families (pr-management, security, issue) are not installed; add them later by re-running /magpie-setup.

A fresh clone needs the snapshot populated before any framework skill is invocable. In your agent harness, run:

/magpie-setup

(or follow .agents/skills/magpie-setup/) to fetch the snapshot per the committed lock, scaffold the gitignored symlinks, and install the post-checkout hook that re-creates them on each worktree checkout.

Adopter-specific modifications to framework workflows live in .apache-magpie-overrides/ (committed) — never edit the snapshot directly. Framework changes go via PR to apache/magpie.

License

Apache License 2.0.