Copyable CI setups shared across Versable apps
One subfolder per pipeline: the files an app drops into place, plus the document explaining them.

What is this?#

A folder index rather than a package, so it carries the house README shape only where the shape earns its place: title, subtitle, an intro table, and the growth rules. There is nothing to install and nothing to run, so there is no Quick Start and no architecture diagram.

The docs-pages status, stated plainly#

docs-pages/ shipped a docs-pages.yml workflow that consuming apps copied, publishing to https://<owner>.github.io/<repo>/. That path was retired. Both consumers deleted the workflow (walmart-mvp in PR #44, chore/retire-docs-pages; speedway alongside it) and replaced it with a twelve-line docs-nexus.yml that calls a shared workflow in versable-git/slack-automation and publishes to https://tech.versable.ai/<repo>/docs/ behind the company login.

So the workflow half of this template has zero live consumers today.

The theme half moved, and the dead copy is gone. This folder used to hold brand.css, mkdocs.yml, nav-glide.js, overrides/ and the logo, byte-identical to the copies in slack-automation's docs-kit/, which is what the nexus actually reads. Editing the copy here changed no published site and reported no error, so on 2026-08-13 it was retired to a pointer README rather than kept as a decoy. One editable copy of the theme exists now, in slack-automation.

The decisions behind all of this are recorded at ../docs/adr/005-docs-publishing.md (why docs publish to one gated nexus) and in slack-automation's docs/adr/001-ui-kit-separation.md (repos stay separate, docs colocate, docs-kit owns the docs tooling path).

How this folder is meant to grow#

One directory per pipeline, named for the job it does rather than the tool it uses, because tools get replaced and jobs do not. The docs-pages case is the proof: the job outlived its tool by about a week.

pipelines/<job-name>/
  README.md      · what it does, every input, the steps, the preconditions
  <files>        · exactly what the consuming app copies, nothing else

Three rules keep a second and third pipeline from forcing a restructure:

Documentation sits beside its template, never in a shared file. A single combined guide would have to be edited by every pipeline that lands, and would grow a table of contents nobody maintains.

No app names in shared paths. A template refers to the consuming app through inputs it declares. docs-pages/ names walmart only as its worked example, and that reference lives in prose, not in a path or a default.

A pipeline earns its place here by having two plausible consumers. One consumer means it belongs to that app. This is the same split rule docs/app-patterns/README.md applies to methods.

A fourth rule, learned from docs-pages: a retired pipeline says so in its own first paragraph. A template that reads as current while nothing uses it costs someone a day before they discover it, which is exactly what happened when 51 doc backlinks kept pointing at the retired address and nothing failed.

What does not belong here#

App-specific deployment wiring. docs/app-patterns/03-deploying-on-gcp.md covers the GCP deploy method because it is a method; the Cloud Build triggers that implement it are per-app infrastructure and stay with the app.

Related#

• ../docs/app-patterns for the methods these pipelines implement
• docs/app-patterns/06-writing-a-repo-readme.md for the README shape this file partially follows, and why it only partially follows it