Skip to main content

Automation model

End-to-end GitLab automation between workflow repositories and docs-portal.

Pipeline sources​

SourcePortal behavior
Push to develop / masterLint → validate mirrors → build → Pages
Downstream trigger from workflow repoSync → validate → commit mirror → build → Pages
Manual SYNC_MODE=all (web)Full sync all active workflows

Workflow repo pipeline (example: superbuild)​

Stages: validate → trigger

1. workflow-docs:contract​

Runs on develop when docs/**/* changes.

  • Confirms docs/workflow-manifest.yaml, portal-integration.md, navigation-meta.md
  • Validates manifest workflow_id and version

2. trigger:docs-portal​

Triggers multi-project pipeline:

trigger:
  project: libesys/ai-workflows/docs-portal
  branch: develop
  strategy: depend
  forward:
    pipeline_variables: true
variables:
  WORKFLOW_SYNC_ID: superbuild
  WORKFLOW_SYNC_REF: $CI_COMMIT_SHA
  WORKFLOW_SYNC_PROJECT: $CI_PROJECT_PATH
  SYNC_MODE: single
  PORTAL_SYNC_COMMIT: "true"

strategy: depend blocks the workflow pipeline until the portal pipeline completes — failures are visible upstream.

Portal pipeline (docs-portal)​

Defined in .gitlab-ci.yml + .gitlab/workflow-sync.yml.

Sync stage (sync:workflow)​

When WORKFLOW_SYNC_ID is set:

  1. Clone workflow repo at WORKFLOW_SYNC_REF using CI_JOB_TOKEN
  2. python scripts/sync_workflow.py <id> --commit
  3. Update sidebars*.ts from manifest sidebar_order
  4. Commit and push mirror changes to develop when PORTAL_SYNC_COMMIT=true

Validate stage​

JobWhen
validate:importAfter sync trigger — full manifest/registry validation
validate:mirroredEvery push — portal-owned files and target dirs exist

Build and Pages​

Unchanged Docusaurus flow:

Numbered end-to-end flow​

  1. Author edits superbuild-workflow/docs/ on develop
  2. Workflow CI validates portal contract files
  3. Workflow CI triggers docs-portal downstream pipeline (strategy: depend)
  4. Portal clones superbuild at WORKFLOW_SYNC_REF
  5. sync_workflow.py updates docs-superbuild/ (preserves intro.md)
  6. Sidebar updated from manifest order
  7. validate_workflow_import.py checks contract coherence
  8. Automated chore(sync): … commit lands on develop (if diff)
  9. npm run build with branch-appropriate DOCS_SITE_URL
  10. pages publishes preview site
  11. Workflow pipeline marks trigger job pass/fail based on portal result

Required GitLab configuration​

docs-portal project​

SettingValue
Settings → CI/CD → Pipeline triggersInbound triggers from workflow projects allowed
Settings → CI/CD → Job token permissions → OutboundEnable outbound access; add each workflow project (portal clones upstream)
Settings → CI/CD → Job token permissions → InboundAdd workflow projects that trigger portal (optional hardening)
Settings → CI/CD → Job token permissions → Allow Git pushEnable if automated chore(sync): commits push via CI_JOB_TOKEN
Pages custom domainesys-ai.org on production (master) only
Variables (optional)GITLAB_SYNC_TOKEN — project access token with read_repository (clone) and write_repository (push) if job token is insufficient

Each workflow project​

SettingValue
CI/CD variablesDOCS_PORTAL_PROJECT, WORKFLOW_SYNC_ID (or hardcode in .gitlab-ci.yml)
Multi-project pipelinesPermission to trigger docs-portal

Token scopes (if using project access token)​

  • read_repository on workflow repos (portal clone)
  • write_repository on docs-portal (automated sync commit push)

Security and governance​

  • Workflow repos remain source of truth — portal tokens only clone and mirror
  • Automated commits use a dedicated bot identity (docs-portal sync)
  • Manual edits to mirrored files are discouraged; sync overwrites on next trigger
  • Downstream triggers are scoped to docs/** changes on develop

Local parity​

Developers run the same sync without CI:

pip install -r requirements-sync.txt
python scripts/sync_workflow.py superbuild --source ../superbuild-workflow
python scripts/validate_workflow_import.py superbuild --source ../superbuild-workflow
npm run build