How this wiki is built & deployed

A short tour of the moving parts behind the wiki — what runs where, who owns what, and why we deploy it the way we do.

The 30-second version

Source: Markdown / MDX in this repo (ehabmostafa_microsoft/azure-wiki).
Generator: Docusaurus 3.9 builds a static site.
Host: Azure Static Web Apps (SWA) — ehab-azure-wiki-dp300.
Deploy: Manual, from the author's laptop, using the SWA CLI.
Why manual: GitHub Actions hosted runners are blocked by the GitHub Enterprise org policy on this account, so CI is not an option today.
Freshness check for Microsoft Learn references: a Node script (scripts/check-learn-freshness.mjs), run daily in the cloud by an Azure Container Apps Job (job-learn-refresher, cron 0 6 * * * UTC) that opens a PR when drift is detected.

End-to-end pipeline

Legend — Blue: author actions. Orange: local build & deploy. Green: Azure hosting. Purple: daily automation (ACA Job). Yellow: security perimeter (Managed Identity + Key Vault + ACR Pull).

Why manual deploy (for now)

The repo lives in a GitHub Enterprise org where GitHub Actions hosted runners are disabled by policy. Every push that triggers a workflow fails in ~3 seconds with:

GitHub Actions hosted runners are disabled for this repository. For more information please contact your GitHub Enterprise Administrator.

Self-hosted runners aren't desired (extra infra to keep patched), so the deploy workflow was removed and the author runs the deploy from their laptop. The full command is in the repo README.

What lives where

Concern	Where	Notes
Content (the wiki)	`docs/*/.md` and `*.mdx`	Sidebars are auto-generated from folder structure
Site config	`docusaurus.config.ts`	Navbar, theme, search, Mermaid
Style guide & contributing	`STYLE_GUIDE.md`, `CONTRIBUTING.md`, `pages-template.mdx`	New pages start from the template
Static assets	`static/img/diagrams/`, `static/img/dp-300/`	SVG / PNG diagrams
Architecture diagram source	`docs/wiki-process.drawio`	Open in diagrams.net
Microsoft Learn freshness	`scripts/check-learn-freshness.mjs` + `.learn-cache.json`	Hashes Learn pages, flags drift
SWA hosting	RG `rg-azure-wiki`, sub `<your-subscription-name>`	Free tier

Deploy procedure (manual)

cd "c:\Users\ehabmostafa\OneDrive - Microsoft\Work\Projects\azure-wiki"
npx docusaurus build

$env:SWA_CLI_DEPLOYMENT_TOKEN = (
  az staticwebapp secrets list `
    --name ehab-azure-wiki-dp300 `
    --resource-group rg-azure-wiki -o json |
  ConvertFrom-Json
).properties.apiKey

npx @azure/static-web-apps-cli deploy .\build --env production

Typical deploy time: ~60 seconds (build) + ~30 seconds (upload).

Microsoft Learn freshness — implementation

Aspect	Detail
Runner	Azure Container Apps Job `job-learn-refresher` — Schedule trigger, cron `0 6 * * *` UTC
Image	`node:20-alpine` + `git` + `gh` CLI, built from `ops/learn-refresher/`
Auth to GitHub	Fine-grained PAT (Contents RW + PRs RW + Metadata R, repo scoped) stored in Key Vault secret `github-pat`; the Job's user-assigned MI has Key Vault Secrets User and consumes it via Container Apps `secretRef`
Auth to ACR	Same MI has AcrPull on the registry
Output	When drift is detected: opens a PR `bot/learn-freshness/YYYY-MM-DD` against `main`. Author reviews and merges; nothing auto-deploys.
Logs	App stdout/stderr in Log Analytics (`log-azure-wiki`); execution history in the Azure portal
IaC	Bicep + `azd` — see `infra/` and `azure.yaml`. Deploy with `azd up`
Cost	ACA Consumption + ACR Basic ≈ $0–$2/mo; subscription budget alert configured at $5/mo

Editing this diagram

The diagram above is Mermaid (rendered natively by Docusaurus). To edit it, just change the fenced ```mermaid block on this page.

A draw.io copy of the same flow lives at docs/wiki-process.drawio for offline editing — open it in diagrams.net (File → Open from → GitHub).

The 30-second version​

End-to-end pipeline​

Why manual deploy (for now)​

What lives where​

Deploy procedure (manual)​

Microsoft Learn freshness — implementation​

Editing this diagram​

See also​