---
title: "ADR-0008: Publish Nimbus on GitHub Pages"
---

> Documentation Index
> Fetch the complete documentation index at: https://nclsppr.github.io/project-foundation/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-0008: Publish Nimbus on GitHub Pages

- Status: accepted
- Implementation status: in progress
- Date: 2026-08-11
- Last verification: 2026-08-11, local audience-filtered build with the `/project-foundation` base path
- Owner: Nicolas Pieper
- Supersedes: none
- Superseded by: none

## Context

Project Foundation builds Nimbus during verification, but it does not publish
the generated site. Selecting `main` as a GitHub Pages branch does not run the
Astro build. The branch contains source files and no root `index.html` file.

The complete local Nimbus build also includes every documentation visibility.
ADR-0003 prohibits publication of that build without an audience filter. A
deployment must exclude internal content and must support the repository base
path used by GitHub Pages.

## Decision problem

How can Project Foundation publish useful Nimbus documentation after each
verified change without committing generated files or exposing an unauthorized
documentation audience?

## Considered options

### Publish `main` as a branch source

Advantage: GitHub Pages configuration is small.

Limitations: GitHub Pages receives the repository sources, not the built Astro
site. No root `index.html` file exists. This option also has no audience gate.

### Commit the generated site to a publication branch

Advantage: GitHub Pages can serve the committed output directly.

Limitations: Generated files enter Git history and can drift from their
Markdown sources. A failed or interrupted update can leave stale pages.

### Deploy a verified Actions artifact

Advantages: The workflow builds from the selected commit, applies an explicit
audience filter, verifies the output, and deploys one immutable artifact. The
generated site does not enter Git history.

Limitations: Publication depends on GitHub Actions and GitHub Pages. The target
repository must enable Pages.

## Decision

Use a dedicated GitHub Actions workflow to publish Nimbus from `main`. Build the
site with the URL metadata returned by GitHub Pages. Upload `docs-nimbus/dist`
as a Pages artifact and deploy it to the `github-pages` environment.

Authorize the `public` and `reference` visibility values for this repository.
Exclude `internal` and `archive`. The reference collection contains the
foundation decisions, profiles, templates, examples, and Nimbus maintenance
guide. These files are stable inputs for foundation users and are suitable for
the public documentation surface.

Use `NIMBUS_VISIBILITIES` as the generic publication filter. Require a
publication source URL. If an included page links to an excluded source file,
link to the immutable repository source for the deployed commit instead of
generating an unauthorized Nimbus page.

Clear the generated site, Astro content cache, and Nimbus cache before each
build. This prevents a filtered build from retaining a route that a previous
complete local build generated.

Apply `NIMBUS_BASE_PATH` to site routes and generated metadata. Verify that the
publication contains no origin-root URL that would leave the repository path.

Pin each third-party action by commit SHA. Keep the GitHub Pages workflow local
to Project Foundation. Do not copy this hosting choice into generated projects.

## Consequences

### Positive

- The documentation has a stable public URL.
- Each deployment corresponds to one repository commit.
- Internal and archive pages do not enter the artifact.
- Git history contains sources and build logic, not generated site files.
- Repository-subpath navigation, search, metadata, and agent indexes use the
  correct base path.

### Negative

- GitHub Actions and GitHub Pages become deployment dependencies for this
  repository.
- A Pages configuration or permission error can block publication while normal
  repository verification remains successful.
- Reference visibility requires an explicit review before its scope changes.

## Verification

- Run the complete foundation verifier.
- Run the audience-filtered publication build with the production base path.
- Verify that no generated page has `internal` or `archive` visibility.
- Verify that origin-root URLs are absent from the artifact.
- Verify the Pages workflow and deployment for the final `main` commit.
- Open the deployed root page, one reference page, search assets, `llms.txt`,
  and `sitemap-index.xml`.

## Rollback

Revert the workflow and adapter change. GitHub Pages keeps the last successful
artifact until an administrator disables the site or another deployment
replaces it. Restore the last verified workflow commit to republish a known
artifact.

## Review

Review this decision if the repository becomes private, the authorized
visibility set changes, a custom domain replaces the repository path, or
GitHub Pages no longer satisfies the publication requirements.

Source: https://nclsppr.github.io/project-foundation/docs/decisions/adr-0008-publish-nimbus-on-github-pages/index.mdx