Skip to content

CONCEPT Cited by 1 source

Git-based content workflow

Definition

Git-based content workflow replaces a traditional CMS UI with the git repository as the system of record for content. Authors write markdown (or restructured text, MDX, etc.) in their normal editor, open a pull request, reviewers comment and approve on the PR as they would for code, and merging to the main branch triggers a deploy of the rendered site.

It is the natural counterpart to a static site generator: the SSG is the build function, git is the input log, the deploy target (S3 bucket, GitHub Pages, Netlify, CloudFront) is the output cache.

What it replaces

  • Proprietary CMS logins — legacy CMS deployments ("only a limited number of people had access to") gate publishing behind access-control rather than merit. Git-based workflows use the same code-review access the engineering org already runs.
  • No-review publish paths — CMS systems often lack a proposal/review/approve flow; the git PR model makes it first-class.
  • Out-of-band staging — a CD system can render a PR branch to a staging bucket and surface a preview URL on the PR, giving reviewers the final rendered view before merge.

Seen in

  • sources/2020-06-30-zalando-launching-the-engineering-blog — Zalando's engineering blog uses a git-based workflow around Pelican. A make new script scaffolds a new post; authors open a PR; the Zalando Continuous Delivery Platform builds the post (make html) and publishes it to an authenticated preview URL for reviewer sign-off; merging triggers the CD platform's built-in S3 upload feature to re-push output/ to the blog's public bucket, which is then served via Skipper with a route annotation. The pre-commit framework runs a Python validator that enforces required frontmatter keys, year/month folder placement, and an explicit tag allowlist — catching errors at commit time rather than deploy time.

  • Docs-as-code — the same pattern underpins most modern technical-documentation sites: MkDocs / Docusaurus / Astro rendered from a git repo, PRs gating changes, CI publishing to a CDN or S3.

Tradeoffs

  • Git familiarity required — non-engineers authoring content have to learn git and PRs, or rely on web-based editors (GitHub web UI, GitLab IDE) that approximate a CMS experience.
  • Merge conflicts on hot content — two authors editing the same post simultaneously will hit git conflicts rather than the CMS's "last-write-wins" or locking; usually fine because posts are rarely co-authored in real time.
  • Asset management is clunky — images and videos in a git repo bloat history; teams offload large assets to a CDN/object store (Zalando uses img01.ztat.net for blog images) with the repo holding only text.
Last updated · 476 distilled / 1,218 read