Skip to main content

Workflow onboarding

Steps to publish a new workflow repository through docs-portal.

Prerequisites​

  • Workflow repo under ai-workflows/<name>-workflow
  • docs/ directory with workflow documentation
  • GitLab permissions to trigger docs-portal pipelines

1. Prepare workflow repo docs​

Author canonical documentation in the workflow repository docs/ tree.

Copy templates from docs-portal/templates/:

  • workflow-manifest.yaml → docs/workflow-manifest.yaml
  • Add docs/portal-integration.md and docs/navigation-meta.md (see superbuild-workflow/docs/)

2. Define manifest contract​

Edit docs/workflow-manifest.yaml:

FieldPurpose
workflow_idRegistry key (e.g. architecture)
display_titleHuman title
exclude_from_syncMetadata files kept out of portal mirror
sidebar_orderDocusaurus sidebar slugs after portal intro

3. Register in portal registry​

Edit docs-portal/workflows/registry.yaml:

  • Add workflow entry with active: true
  • Set gitlab_project, sync_ref, target_dir, sidebar_file, sidebar_id
  • Match docusaurus_plugin_id and route_base_path to docusaurus.config.ts

4. Register Docusaurus section​

In docs-portal:

  1. Create docs-<workflow>/intro.md (portal-owned landing)
  2. Add docs plugin block and navbar item in docusaurus.config.ts
  3. Create sidebars<Workflow>.ts (sync can populate slugs from manifest)

Or extend registry + run sync after manifest exists — sidebar is updated automatically.

5. Enable GitLab trigger path​

In the workflow repo .gitlab-ci.yml (see templates/gitlab-ci-workflow-snippet.yml):

  • workflow-docs:contract on develop + docs/** changes
  • trigger:docs-portal with strategy: depend

Set WORKFLOW_SYNC_ID to match registry and manifest.

6. Run first sync​

Local (cross-platform):

cd docs-portal
pip install -r requirements-sync.txt
python scripts/sync_workflow.py <workflow_id> --source ../<workflow_id>-workflow
python scripts/validate_workflow_import.py <workflow_id> --source ../<workflow_id>-workflow
npm run build

CI: push workflow docs/ change to develop and verify downstream portal pipeline.

7. Verify navigation and build​

  • Sidebar lists all synced slugs
  • npm run build passes (onBrokenLinks: throw)
  • Preview site section loads at /\<workflow>/intro/

8. Publish​

  • Merge portal changes to develop (preview Pages)
  • Fast-forward master when CI green (production esys-ai.org)

Checklist​

  • docs/workflow-manifest.yaml in workflow repo
  • docs/portal-integration.md and docs/navigation-meta.md
  • Registry entry in workflows/registry.yaml with active: true
  • Docusaurus plugin + navbar configured
  • Portal intro.md created
  • Workflow .gitlab-ci.yml triggers portal
  • GitLab token/trigger access configured
  • First sync + validate + build green