ADR-001: Documentation site hosting for DISH repos

Status: Proposed
Date: 2026-08-29
Authors: Divya Pillai
Ticket: DISH-356

Summary:

  • Prefer to host documentation on Cloudflare Pages, enabling Roche SSO access.

  • Markdown still preferred for most DISH repositories. Exception: the OneDoc pilot in dish-recipes succeeded and is good enough to keep.

Context

DISH work spans many repos, and we want their technical documentation published as browsable sites. The target audience is currently DISH developers and collaborators new to our team conventions. We also want general discoverability across the organization: we will get more external usage as some of our tools become more "self-service", and our documentation should be findable by and useful to a broader Roche audience.

This ADR lives in dish-recipes (the cross-DISH home) because the decision applies to more than one repo. DISH repos are split between GitLab and GitHub, which affects the hosting options. Technical differences, and being between migrations, mean we cannot mandate the same recommendation for all DISH repos.

This ADR focuses on technical documentation. We also have a wide array of non-technical documentation options. This ADR will not attempt to consolidate those resources, but it will briefly note those options before moving on to the core problem of technical documentation.

Technical considerations

The primary technical characteristics:

  • Repo host: Roche is trying to migrate from GitLab to GitHub. GitLab should be phased out by end of 2027. However, most DISH services are still on GitLab. dish-frostbyte and dish-recipes are new, so are on GitHub, specifically roche-innersource.

  • Docs host: via the repo’s native Pages equivalent, via some other Roche hosting solution, or self Cloud hosted. This has implications for who can access pages (Roche SSO vs. GitHub account).

  • Documentation language: AsciiDoc has more viewer-friendly features for prose-based documentation, contributing to the Architecture team’s recommendation. But Markdown is the agentic standard (especially for Claude), and we would not want to duplicate technical documentation that already exists. Further, Markdown has a slight edge for pages that require Javascript.

Some of the implementation options couple these technical characteristics:

  • OneDoc renders only through Antora, whose source is AsciiDoc. OneDoc is flexible about repository and Docs hosts. However, its existing documentation targets GitLab repos and GitLab Pages. For a recent GitHub + Cloudflare example with OneDoc, see the CSCoE Architecture Repo.

  • build.roche.com (Backstage TechDocs) accepts MkDocs (Markdown) only.

  • GitLab Pages requires the source repo to live on GitLab. While access would normally be GitLab account-gated, Roche offers the ability for repos to set access to "public" and gate only on Roche SSO access. See GitLab Pages docs. Bifrost and Storage Service allow everyone (with Roche SSO) to access their Pages, and that’s the default setting for GitLab repos.

  • GitHub Pages requires the source repo to live on GitHub. Roche organization pages are all private access, so they require a GitHub account to view. Collaborators without a GitHub account (whether non-developers, or devs who are blocked due to Roche hitting its GitHub account cap) cannot access GitHub Pages.

  • Roche Cloudflare Pages deployments work for various repos including GitHub. They serve a static site at https://<repo-name>.ghpages.roche.com, gated on Roche SSO. This is the recommended approach for GitHub-based docs that don’t need to lock down access to GitHub accounts. See GitHub Cloudflare Pages docs.

Discoverability

While discoverability is a major concern, none of the existing webhosts + build tools make this automatic. The user needs to manually add their pages to an index, such as:

Since indexing is not guaranteed by any option in particular, it will not be a factor below. Discoverability will primarily come down to access restrictions (GitHub account vs. Roche SSO).

Non-technical documentation

DISH team members can find information in several other places:

  • Slack - gRED org, primary channel #cs-coe-ddc-solutions-platform.

  • Google Drive - within the CSCoE_DDC__All top-level drive, following org structure down to the DISH team folder.

  • Lucid - DISH Team > DDC Data Layer

  • Linear - DDC Data Layer initiative. Note: legacy work tracking is in GitLab repositories, but new work tracking happens in Linear.

These are all suited to different purposes; none are great on their own for technical documentation. Google Docs and LucidCharts may be useful links for technical documentation to reference or import.

Our collaborators may use other documentation in:

  • Confluence: Roche has many different spaces here. It is easy for non-developers to edit. However, spaces vary greatly in how organized or up-to-date they are.

  • gSites - e.g. CS CoE. This offers a useful view of the org structure and has helpful resources for employees. However, it’s difficult to discover existing gSites.

The above are nice structures and documentation-focused, but they have the danger of going out of sync, and they can’t be as easily read or accessed by coding agents. We follow the principle of "Documentation as Code". The rest of this ADR will focus on documentation that lives in a code repository.

Options considered

# Web host Build tool Source format Repos it works with Access gate Verdict

1

Cloudflare Pages (*.ghpages.roche.com)

MkDocs Material

Markdown

Any

Roche SSO

Preferred, reduces doc duplication in repo and is the most accessible

2

Cloudflare Pages (*.ghpages.roche.com)

OneDoc (Antora)

AsciiDoc (convert from Markdown)

Any

Roche SSO

Acceptable when Roche-public documentation is distinctly different from agent-targeted code docs

3

GitHub Pages (*.pages.github.io)

Any

Any

GitHub (roche-innersource)

GitHub account

Rejected — unreadable for account-less collaborators

4

build.roche.com (TechDocs, GCS-backed)

MkDocs (TechDocs)

Markdown

Any

Roche SSO

Rejected — uncertain longevity

5

AWS S3 + CloudFront

Any

Any

Any

Configurable (bespoke)

Rejected — bespoke infra, one-team upkeep

6

GitLab Pages (gredit.pages.roche.com)

Any

Any

GitLab (code.roche.com)

Roche SSO (public tier); GitLab account for stricter tiers

Keep existing, but recommend moving publishing to Cloudflare.

Decision

  • DISH does not host sensitive repositories, so we will not likely need to limit our Pages visibility. Therefore, we should only select options that allow access to anyone with a Roche account. This eliminates GitHub Pages.

  • Generally prefer a low-maintenance solution, resilient to infrastructure migrations and changes in best practices.

    • This slightly favors Markdown over AsciiDoc, despite the architecture team’s recommendation, as existing agent-targeted documentation is written in Markdown.

    • This discourages DIY approaches or less-supported infrastructure, in favor of established deployment patterns that work across infrastructure choice.

  • The GitLab → GitHub migration will go well beyond documentation.

  • "Edit in browser" is a useful feature worth adopting for most of our documentation.

Recommendations per DISH repo:

  1. dish-frostbyte adopts Cloudflare Pages with MkDocs Material.

This repo is highly technical and has a lot of Markdown documentation not yet hosted anywhere. Adopting a new docs standard would be tricky for DISH developers. For now, Markdown docs are the easiest to maintain. This means we can auto-publish much of our existing documentation.

We still need to organize its content better, preferably starting with content for end users/ collaborating systems, with a sub-page for DISH team internal documentation. However, some end user documentation may be a better fit for dish-recipes, especially as it crosses systems.

  1. dish-recipes (this repo) adopts Cloudflare Pages and pilots AsciiDoc + OneDoc.

This repo targets a broader audience and is documentation-focused. Ordinarily these would be arguments in favor of OneDoc. However, the existing DISH Service Hub hosted a clickable Mermaid image with additional Javascript. Rendering was easy in MkDocs Material with full Mermaid support, but it’s trickier in OneDoc with limited built-in support. Migrating requires care to preserve similar functionality, and we may want to experiment with approaches. It is low risk; the repo is new and the site is only used by a handful of DISH developers.

Regardless of source language, this repo must switch deployment to Cloudflare Pages ASAP. The prior GitHub Page required a GitHub account to view, and its URL was autogenerated as https://sturdy-pancake-9m2pwop.pages.github.io/. https://roche-innersource.github.io/dish-recipes redirects to the right page, but the browser doesn’t preserve the Roche-named URL. Moving it to Cloudflare fixes the read-access problem and gives a stable, legible URL (https://dish-recipes.ghpages.roche.com).

  1. Existing GitLab Pages deploys stay as-is, but switch to Cloudflare Pages when they’re ready to prepare for migration.

bifrost, mnemos, and storage-docs publish via GitLab Pages (gredit.pages.roche.com), already gated on Roche SSO. Their services and documentation have existing user bases. Documentation is less difficult to migrate compared to deployment (GitLab Pipelines → GitHub Actions), but it will affect the URL end users navigate to. Replatforming now would require communicating URL changes with end users and could disrupt their existing flows.

This ADR recommends GitLab repos move to Cloudflare Pages when the teams are ready to handle the URL change. It can still happen before the rest of the GitLab → GitHub migration, as the Cloudflare URL should be the same after moving to GitHub.

Either way, the dish-recipes Service Hub can help users better access docs no matter where they are hosted.

How to adopt Cloudflare Pages (GitHub repos)

Per the fk-github guide:

  1. Prerequisites — repo must be in the roche-innersource org (DISH repos already are). Set two repo custom properties (Settings → Code and automation → Custom properties):

    • hosting-status = cloudflare-pages

    • owner-team = dish (the repo’s GitHub Team name)

    The repo name becomes the Cloudflare Pages project name automatically, so it also decides the URL (<repo-name>.ghpages.roche.com).

  2. Workflow — add .github/workflows/cloudflare-pages-deployment.yml: a build job that builds the site and uploads the output directory as an artifact, then a deploy job that calls the pinned reusable workflow. For a Markdown site this build runs mkdocs build --strict over site/; dish-recipes instead runs the Antora build (npm run build) over public/ (see below).

  3. First deploy takes a few minutes for DNS propagation, then the site is live at https://<repo-name>.ghpages.roche.com.

Follow the guide’s best practices: use relative internal links (not absolute URLs), never commit secrets, and don’t host large binaries.

Authoring with OneDoc

The authoritative reference for OneDoc/Antora authoring conventions — navigation files, module structure — is the OneDoc writers' and admins' guides. The CSCoE architecture playbook recommends OneDoc but is not a guide to its conventions.

Consequences

Positive

  • Read access solved for GitHub repos: Cloudflare Pages enables any Roche employee to read via SSO, independent of repo host.

  • Developer-standard format where it matters: existing technical docs stay Markdown and agent-friendly without needing to convert. MkDocs Material is already the standard across gRED and Roche.

  • SHA-pinning compliant: the reusable workflow and its internal actions are pinned to SHAs, satisfying the org’s sha_pinning_required policy.

  • Legible URLs: <repo>.ghpages.roche.com instead of a random *.pages.github.io slug.

Negative / trade-offs

  • ADR divergence: cannot fully adopt the Architecture Team recommendation of OneDoc. Even a pilot implementation in dish-recipes results in divergent documentation systems across DISH. This could increase the maintenance burden over time.

  • OneDoc-specific cons:

    • Advanced styling / JS rendering: OneDoc lacks some of the MkDocs Material built-ins, so website-like styling is more challenging. dish-recipes is pushing the boundaries of what a docs-as-code language can do, acting more like a dynamic website than a standard docs page.

    • Manual navigation: OneDoc discourages AutoNav because it is deprecated and recommends maintaining navigation files manually. Needing to opt in to indexing creates friction that may encourage repository-only documentation, and thus weakens our preference that documentation is visible to external viewers.

    • GitHub README rendering: While GitHub can render README.adoc instead of README.md, one of its quirks is non-standard Mermaid rendering (GitHub Community discussion). This will hit the current dish-recipes README, making it harder for devs to test locally and have parity with the GitHub UI.

  • Preview status: Cloudflare Pages is OneSCM Preview; the reusable-workflow SHA and version may change. Pin the SHA and watch the change-log.

  • Fixed access gate: if we wanted to limit GitHub Pages visibility, we’d need to switch publishing from Cloudflare Pages to GitHub Pages. This is different from GitLab, which could condition Pages access in its repo settings independent of the publishing mechanism.

  • Discoverability: listing (if wanted) is still a manual merge request adding the site URL, which needs GitLab access.

Follow-ups