Roadmap: CI/CD Automation

1. Overview

This roadmap defines the automation improvements for the Domus documentation CI/CD pipeline, eliminating manual triggers and enabling spoke-driven deployments.

Current State

Manual empty commits required to trigger domus-docs builds after spoke repo changes

Target State

Automatic builds triggered by any spoke repo push via repository_dispatch webhooks

2. Documentation Site Architecture

The complete Domus documentation system consists of 6 layers:

Domus Documentation Architecture

2.1. Layer Breakdown

Layer Components Purpose

1. Content Sources

12 spoke repos (domus-*)

AsciiDoc content, organized by domain (ISE, infra, secrets, etc.)

2. Aggregator

domus-docs + antora-playbook.yml

Orchestrates all content sources, defines site structure

3. UI Bundle

domus-antora-ui

Catppuccin Mocha theme, Handlebars templates, CSS

4. Build Pipeline

GitHub Actions + Antora + Kroki

Fetches content, renders diagrams, builds static site

5. Deployment

Wrangler + Cloudflare Pages

Global CDN distribution, edge caching

6. Authentication

Cloudflare Access

GitHub OAuth SSO, authorized users only

3. CI/CD Automation Flow

The current vs target automation architecture:

CI/CD Automation Flow

3.1. Current Pain Point

When you push to a spoke repo (e.g., domus-captures), the aggregator (domus-docs) doesn’t know about it:

# Push spoke repo
git -C domus-captures push origin main
# Nothing happens...
# Must manually trigger domus-docs
git -C domus-docs commit --allow-empty -m "chore: Trigger rebuild"
git -C domus-docs push

3.2. Target Solution

Spoke repos automatically notify domus-docs via GitHub’s repository_dispatch API:

# Push spoke repo
git -C domus-captures push origin main
# → GitHub Action in domus-captures fires repository_dispatch
# → domus-docs receives event and starts build
# → Cloudflare Pages deploys automatically

4. Phase 1: Repository Dispatch Webhooks

4.1. Objectives

  • Automatic builds when any spoke repo is pushed

  • Single workflow file templated across all spoke repos

  • Secure dispatch using GitHub App or PAT with minimal scope

4.2. Tasks

# Task Priority

1.1

Create repository_dispatch workflow in domus-docs to receive events

HIGH

1.2

Create reusable dispatch workflow for spoke repos

HIGH

1.3

Add dispatch workflow to all 12 spoke repos

HIGH

1.4

Set up GitHub secret for cross-repo dispatch authentication

HIGH

1.5

Test end-to-end: spoke push → hub build → deploy

HIGH

4.3. Implementation Details

domus-docs receiver workflow:

# .github/workflows/receive-dispatch.yml
name: Receive Spoke Dispatch
on:
  repository_dispatch:
    types: [spoke-updated]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Log trigger source
        run: echo "Triggered by ${{ github.event.client_payload.repo }}"
      - uses: actions/checkout@v4
      # ... existing Antora build steps

Spoke repo sender workflow:

# .github/workflows/dispatch-hub.yml
name: Dispatch to Hub
on:
  push:
    branches: [main]

jobs:
  dispatch:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger domus-docs build
        uses: peter-evans/repository-dispatch@v3
        with:
          token: ${{ secrets.DISPATCH_TOKEN }}
          repository: EvanusModestus/domus-docs
          event-type: spoke-updated
          client-payload: '{"repo": "${{ github.repository }}"}'

4.4. Success Criteria

  • Push to any spoke repo triggers domus-docs build within 30 seconds

  • No manual intervention required

  • Build logs show which spoke repo triggered the build

5. Phase 2: Build Optimization

5.1. Objectives

  • Reduce build time with caching

  • Parallel content source fetching

  • Incremental builds where possible

5.2. Tasks

# Task Priority

2.1

Cache npm dependencies between builds

MEDIUM

2.2

Cache Antora content sources (.cache/antora)

MEDIUM

2.3

Cache UI bundle download

LOW

2.4

Measure and optimize Kroki diagram rendering time

LOW

5.3. Current Build Time

Step Duration

Checkout

~5s

npm install

~30s

Fetch UI bundle

~10s

Fetch 12 content sources

~45s

Antora build

~60s

Wrangler deploy

~20s

Total

~3 min

5.4. Target Build Time

With caching: < 90 seconds

6. Phase 3: Preview Deployments

6.1. Objectives

  • PR preview environments on Cloudflare Pages

  • Automatic preview URLs posted to PR comments

  • Preview cleanup after PR merge/close

6.2. Tasks

# Task Priority

3.1

Configure Cloudflare Pages branch previews

MEDIUM

3.2

Create PR comment workflow with preview URL

MEDIUM

3.3

Test preview deployment on domus-docs PRs

MEDIUM

3.4

Document preview workflow for spoke repo PRs

LOW

7. Phase 4: Quality Gates

7.1. Objectives

  • Link validation before deploy

  • AsciiDoc syntax validation

  • Broken xref detection across components

7.2. Tasks

# Task Priority

4.1

Integrate antora-xref-validator extension

MEDIUM

4.2

Add link checker (lychee or similar)

LOW

4.3

Fail build on broken xrefs

LOW

4.4

Generate validation report as build artifact

LOW

8. Spoke Repos

The following repos will receive the dispatch workflow:

Repository Component

domus-infra-ops

Infrastructure Operations

domus-ise-linux

Linux 802.1X EAP-TLS

domus-ise-windows

Windows 802.1X EAP-TLS

domus-ise-ops

ISE Operations

domus-linux-ops

Linux Operations

domus-netapi-docs

Network Automation CLI

domus-secrets-ops

Secrets Management

domus-identity-ops

Identity & SSO

domus-automation-ops

Automation Templates

domus-siem-ops

SIEM Operations

domus-captures

Work Chronicles

domus-python

Python Tools

9. Reference Resources

10. Revision History

Date Author Changes

2026-02-13

EvanusModestus

Initial roadmap creation