Skip to main content

Content workflow

GitLab-native content workflow (openstandardagents.org)

Last updated: 2026-03 Backend: GitLab only (no separate API or database)

Overview

All content for the openstandardagents.org site is driven by GitLab: tasks are Issues, drafts are branches and merge requests that change files under website/content/, and publishing is a human-approved merge that triggers the existing CI and GitLab Pages deploy.

Conventions

Branch names

  • Content branches: content/<type>/<slug-or-date>
    • Blog: content/blog/2026-03-autonomous-workflow
    • Research: content/research/OpenAPI-AI-Agents-Standard
    • Docs: content/docs/custom-doc-slug
  • Rule: Draft content lives under website/content/ on a branch. MR target is release/v0.4.x (or main per project policy).

Content paths

  • Blog: website/content/blog/ (markdown; slug from filename).
  • Research: website/content/research/ (markdown; slug from filename).
  • Docs: website/content/docs/ (markdown/MDX; path from slug).

Issue labels

  • content::blog — blog post request
  • content::research — research paper request
  • content::docs — documentation request
  • workflow::content-draft — ready for agent or human to create a draft (branch + MR)
  • ready-for-dev — optional; used by Duo flow-triggers

Lifecycle

  1. Task: Create a GitLab Issue (optionally use the "Content request" template). Add labels (e.g. content::blog, workflow::content-draft).
  2. Draft: Create a branch from the issue (e.g. content/blog/2026-03-my-post), add or edit files under website/content/, push, and open an MR targeting release/v0.4.x.
  3. Review: Duo/Code Review or assign reviewer; CI runs (validate, build, link check, etc.).
  4. Approve: Human merges the MR.
  5. Publish: Merge to release/v0.4.x triggers CI; pages job deploys to staging. Merge release to main and run the manual pages job for production (openstandardagents.org).

GitLab Ultimate and Agent Platform

Security and compliance

  • Security policies: The project (or group) uses GitLab Ultimate security policies. Content MRs are scanned (SAST, Secret Detection, etc.); avoid pasting secrets into content.
  • Policy project: Group security policies are defined in the linked policy project (e.g. blueflyio/security-policies). Scan execution and MR approval rules apply to all branches including content/*.
  • Compliance: Use GitLab audit events and merge approvals to see who approved content (merge by user, MR approval rules).
  • Audit: In the group or project, go to Security and Compliance > Audit events to see who merged which MR, when, and from which branch. Filter by project or by event type (e.g. merge request) for content approvals.
  • Approval rules: Optional MR approval rules (e.g. require one approval for content/* MRs) can be set at project Settings > Merge requests > Approval rules.

Observability

  • GitLab Observability: Enable for the group or project to view pipeline and deploy metrics (e.g. Pages deploy success, build duration). Requires a dedicated Observability token (not a PAT); set at group Settings > CI/CD > Variables as GITLAB_OBSERVABILITY_TOKEN.
  • Dashboard: Group or project Observability dashboard: https://gitlab.com/groups/blueflyio/-/observability (or project-level). Use it to monitor pipeline success rate, build duration, and Pages deploy status for content MRs and release branches.
  • API Monitoring: Optional API Monitoring Explorer (same Observability surface) for any HTTP endpoints the site or automation calls.
  • What to watch: For the content workflow, track pipeline duration for content/* and release/v0.4.x; failed jobs (e.g. content:validate, build, pages); and deploy success to GitLab Pages after merge.

Workspaces (optional)

  • For human-in-the-loop editing: open a GitLab Workspace from the content MR branch, edit in the browser/IDE, push. Duo/flow can run on the same branch. No extra backend; Workspaces use GitLab infrastructure.

Duo flows and service account

  • A content-draft flow can be triggered when an issue is labeled workflow::content-draft (and optionally content::blog / content::research / content::docs). The flow uses a Service Account to create a branch, add files under website/content/, and open an MR. See .gitlab/duo/flow-triggers.yml and the content-draft flow definition in .gitlab/duo/.
  • MR review: Use the existing Code Review flow or assign Duo as reviewer so content MRs get automated review comments.

What we do not do

  • No new API routes for content in the Next.js app (no /api/drafts, no database). Content stays file-based; the build reads from website/content/.
  • No new backend service. GitLab Issues, MRs, CI, and Pages are the backend.