Publishing

Build ownership

The central workflow checks out this site, separately checks out the shared theme, fetches registered product documentation, builds and tests the API on Node.js 22, builds Hugo, and deploys the complete public/ folder together with the api/ Azure Functions backend to Azure Static Web Apps.

A failed fetch or build prevents deployment. Production runs are serialized. Theme and product commit SHAs are included in the GitHub Actions run summary. Product content tracks its current default branch; theme adoption is explicit through theme-ref.txt.

GitHub App setup

Use separate read and notification Apps to keep the private key held by a product workflow from granting write access to source repositories.

Central read App

Grant Contents: read and install it only on the theme and registered product repositories under the central repository’s GitHub owner.

Configure in the central repository:

CI mints a short-lived installation token limited to the registered source repositories and theme. Checkout credentials are not persisted. Import authentication is configured only for the fetch step.

Product notification App

Grant Contents: write, required for GitHub’s repository dispatch API, and install it only on the central docs repository. In each product repository configure:

The notification workflow requests a token for that one target repository. It never receives an Azure deployment credential.

Azure Static Web Apps

The existing Static Web App is https://proud-water-0ad897503.4.azurestaticapps.net/. Use this repository’s deployment workflow rather than a second generated workflow. Store its deployment token in the central repository’s AZURE_STATIC_WEB_APPS_API_TOKEN Actions secret, never in a tracked file or chat. The workflow builds Hugo explicitly and sets skip_app_build: true, app_location: public, and output_location: "". This skips only the frontend build. The API uses api_location: api, skip_api_build: false, and api_build_command: npm run build so Azure builds and packages the TypeScript functions. The site configuration sets platform.apiRuntime to node:22. Configure the API application settings described in the API README in Azure; CI does not need these service credentials to run the tests.

Attach the custom domain docs.kyanis.at in Azure and complete the DNS verification and routing records Azure provides. Verify TLS and the /en/, /de/, and root URLs. Until then, CI defaults to the Azure hostname. After attaching the domain, set DOCS_BASE_URL to https://docs.kyanis.at/ and rebuild. Local production-style builds default to the custom domain in hugo.toml; set HUGO_BASEURL to override that value.

This is a static multi-page site; do not enable an SPA fallback that rewrites missing documentation to a homepage.

Triggers and trust

The central workflow runs on default-branch pushes, manual runs on the default branch, and product-docs-updated repository dispatch events. Product workflows notify only after documentation changes reach their default branch.

Pull-request validation runs importer tests with local Git fixtures and API build/tests without secrets, including for forks. It does not access the private theme or real product repositories. The trusted central workflow additionally builds fixture pages with the real theme and performs the full imported-content build.

First deployment checklist

1. Verify all registered repository names and read App access.
2. Check that theme-ref.txt identifies an accessible published theme commit.
3. Configure the GitHub App and Azure settings above.
4. Install the product-side notification workflow in the actual product repo.
5. Run the central workflow manually on the default branch.
6. Check its recorded source SHAs, generated pages, images, and language links.
7. Trigger a real product documentation update and verify the event and rebuild.
8. Verify the Azure custom domain and HTTPS.

Workflow files alone do not create Azure resources, install GitHub Apps, or configure DNS. Do not treat those external steps as complete until verified.