Universal Documentation Engine Operational Documentation

Appearance

Admin & Automated CI/CD Deployment ​

This operator guide details how system administrators and DevOps engineers deploy the Universal Document Engine (UDE) inside secure, automated high-performance enterprise CI/CD environments.

🛠️ Admin Installation Specs ​

UDE is proprietary software. It is not published to any package index — not public PyPI, not a private mirror — so it cannot be installed with a plain pip install universal-document-engine, pipenv install universal-document-engine, or poetry add universal-document-engine command. Those commands will simply fail to resolve: no such installable package exists anywhere for them to find.

Production runners obtain UDE through a private, authenticated distribution channel scoped to this repository's own access control (a GitHub Release asset, or a direct pip install of a locally-downloaded wheel file — never a registry lookup). The exact mechanism is still being finalized; see restructure/ude_deployment_plan.md and restructure/restructure_plan_claude.md in the Pipeline umbrella repo for the current design.

🤖 Continuous Integration Workflow ​

All automated workflows in the project are configured under each repository's own .github/workflows/ directory. As of 2026-07-22, every product site self-deploys from its own repository — there is no combined, umbrella-owned build.

:::important Workflow Comment Block Requirement: Every GitHub Actions workflow in the UDE repositories must start with a structured comment block documenting its configuration:

  • Purpose: Main goal of the workflow.
  • Triggers: Events or branches that trigger execution.
  • Required Secrets: Any GitHub repository secrets used.
  • Expected Execution Time: Estimated execution duration.

:::

The example below walks through engine's own publish-api-ref.yml — the pattern (checkout → build → deploy → alert) is the same shape design-docs, user-docs, and ude_promotion's own deploy.yml files follow, each in their own repository.

Step 1: Checkout (no cross-repo access needed) ​

yaml
- name: Checkout Code
  uses: actions/checkout@v7

A self-deploy workflow only ever checks out its own repository — GitHub Actions grants a workflow native read access to the repository it runs in, with no deploy key or PAT required. This is unlike the pre-2026-07-22 architecture, which needed PIPELINE_GITHUB_TOKEN/ENGINE_PAT to check out other repositories from a central umbrella workflow — see user-docs/docs/deployment/secrets.md for what happened to those tokens.

Step 2: Runner Environment Setup ​

yaml
- name: Install System Dependencies (Doxygen)
  run: sudo apt-get update && sudo apt-get install -y doxygen

Installs the Doxygen preprocessor directly onto the standard Ubuntu runner host machine.

Step 3: Parse, Render, Build ​

bash
# 1. Parse the engine's own Python source into an intermediate representation
python -m ude.cli parse --doc-config ./ude_self_doc_config.json --output-ir /tmp/catalog.json.gz

# 2. Render Markdown from that IR
python -m ude.cli render --input-ir /tmp/catalog.json.gz --doc-config ./ude_self_doc_config.json --output hugo-site/content

# 3. Compile the Hugo static site from the rendered Markdown
hugo -s hugo-site -d ../public --baseURL https://ude-api-ref.pages.dev/ --gc --minify --cleanDestinationDir

ude_self_doc_config.json lives inside engine itself (moved there 2026-07-22 — it used to live in user-docs as ude_config_self.json, resolved via a symlink back into engine). It points src_dir at engine's own Python source (ude, relative to the config file's own directory — no symlink needed now that the config lives alongside the source it documents), collects it with "collector": {"type": "doxygen", "language": "python", "doxyfile_template": "Doxyfile"}, parses it with "parser": {"type": "doxygen_xml"}, and renders it with "renderer": {"type": "hugo_markdown"}.

🌐 Cloudflare Pages Deployment ​

After the build stages complete successfully, the runner deploys the compiled static directory directly to Cloudflare Pages via wrangler:

yaml
- name: Deploy to Cloudflare Pages
  uses: cloudflare/wrangler-action@v3
  with:
    apiToken: ${{ secrets.CF_API_TOKEN }}
    accountId: ${{ secrets.CF_ACCOUNT_ID }}
    command: pages deploy public --project-name=ude-api-ref --branch=main

This updates the live site instantly at its *.pages.dev domain (or a custom domain, once attached) with zero downtime. cloudflare/pages-action@v1 (the deprecated/archived predecessor to wrangler-action) is no longer used anywhere in this ecosystem as of 2026-07-22.

A newly-created Cloudflare Pages project must exist before the first deploy — wrangler pages deploy does not create the project automatically on first use, it only creates the deployment once the named project already exists. Create it once via the Cloudflare dashboard (or wrangler pages project create <name> --production-branch=<branch> — set the production branch explicitly if it differs from Cloudflare's default, or deploys to a non-default branch will land as "Preview" deployments invisible on the project's main domain).

📂 Access Control ​

Some Cloudflare Pages projects in this ecosystem have Cloudflare Access (Zero Trust) enabled at the project level — this is dashboard/API configuration, entirely separate from the deploy workflow itself, and is not something any deploy.yml in this ecosystem configures. If a project you expect to be public returns a redirect to a cloudflareaccess.com login page instead of its real content, check that project's Access policy in the Cloudflare Zero Trust dashboard rather than the deploy workflow.

  • user-docs/docs/deployment/secrets.md — secrets referenced above
  • user-docs/docs/deployment/cicd-pipelines.md — how this fits into the wider pipeline matrix
  • .github/AGENTS.md — per-workflow trigger and success-indicator catalog

Copyright © 2026