claude-foundations/platformhub/architecture.md

Platform Hub Architecture

What Is Platform Hub?

Platform Hub is Octopus Deploy's mechanism for creating reusable deployment process templates that can be shared across spaces. It enables platform engineering teams to define standard deployment pipelines that project teams consume.

Key Concepts

The Three Layers

┌─────────────────────────────────────────────────────────────┐
│  Platform Hub Git Repo                                      │
│  (e.g., github.com/org/taniwha.platform_hub)                │
│                                                             │
│  .octopus/process-templates/                                │
│    ├── standard-go-service-deploy.ocl                       │
│    ├── python-ml-service-deploy.ocl                         │
│    ├── payment-service-deploy.ocl                           │
│    └── ...                                                  │
│                                                             │
│  Defines: steps, parameters, scripts                        │
│  Stored in: Git (OCL files)                                 │
└──────────────────────────┬──────────────────────────────────┘
                           │ Octopus reads OCL from Git
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Platform Hub (Octopus Instance)                            │
│                                                             │
│  Publishing & Sharing:                                      │
│    - Version management (semantic versioning)                │
│    - Space visibility (which spaces can use each template)  │
│    - Stored in: Octopus database (NOT Git)                  │
└──────────────────────────┬──────────────────────────────────┘
                           │ Projects reference templates
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Project (in any shared space)                              │
│                                                             │
│  deployment_process.ocl:                                    │
│    process_template "deploy-my-app" {                       │
│      process_template_slug = "standard-go-service-deploy"   │
│      version_mask = "1.X"                                   │
│      parameter "cloud_target" { value = "aws" }             │
│    }                                                        │
│                                                             │
│  Stored in: Project's Git repo (if CaC) or database        │
└─────────────────────────────────────────────────────────────┘

What Lives Where

Artifact	Storage	Managed By
Process template OCL (steps, scripts, parameters)	Git repo	Engineers via commits
Template versioning (major.minor.patch)	Octopus database	UI (publish action)
Template sharing (space visibility)	Octopus database	UI only — no API/CLI
Step templates (ActionTemplates)	Octopus database, per-space	API or UI
Project consumption of templates	Project Git repo (CaC) or DB	Engineers or API

Step Templates vs Process Templates

These are different things that complement each other:

	Step Templates	Process Templates
Scope	Single step (one action)	Multi-step pipeline
Storage	Octopus DB, per-space	Git repo (OCL)
Created via	API or UI	Git commit
Referenced by	Octopus.Action.Template.Id	process_template_slug
Cross-space	No — space-scoped	Yes — via Platform Hub sharing
Use in process templates	Cannot reference cross-space	N/A

Critical: Process templates in Platform Hub cannot reference step templates from other spaces. If you have reusable step templates in Space A, a process template in Platform Hub cannot use them. Instead, process templates must use inline action_type definitions.

Git Repo Structure

The Platform Hub repo has a fixed structure that Octopus expects:

.octopus/
  process-templates/
    template-slug-name.ocl     # One file per process template
    another-template.ocl
README.md                       # Optional documentation

• Files must be in .octopus/process-templates/
• File extension must be .ocl
• The filename becomes the template slug (minus .ocl)
• Octopus reads from the main branch (configurable)

Versioning and Updates

• Templates use semantic versioning (major.minor.patch)
• Publishing creates a new version
• Consuming projects use version_mask to control updates:
  • "1.X" — auto-update on minor/patch, manual upgrade for major
  • "1.2.X" — auto-update on patch only
  • "1.2.3" — pinned to exact version
• Major version bumps are breaking changes: parameter renames, step removals
• Minor/patch for non-breaking: new optional params, script improvements, bug fixes

Setting Up a New Platform Hub

1. Create a Git repo (GitHub, Gitea, etc.)
2. Create .octopus/process-templates/ directory
3. Add OCL files (see OCL Syntax Reference)
4. In Octopus: configure Platform Hub to point at the Git repo
5. Templates appear in the UI after Octopus reads the repo
6. Publish each template (UI) to create a version
7. Share each template with desired spaces (UI)

References

• Process Templates Docs
• Template Parameters
• Publishing & Sharing
• Best Practices