STACKIT Docs Integration

This document describes how Professional Services Terraform examples are synced as .mdx asset cards to the STACKIT documentation assetcontainer.

Overview

Each example in examples/ declares metadata in stackit.docs.yaml. On merge to main, a GitHub Actions workflow generates .mdx asset files and opens a PR to the stackitcloud/docs-content repository under docs/cloud-framework/architecture-framework/assetcontainer/professional-services/.

Directory Structure

professional-service/
├── examples/
│   ├── alb-tls-examples/
│   │   ├── README.md
│   │   ├── stackit.docs.yaml    # <-- metadata for docs card
│   │   └── ...
│   ├── ske-azure-arc-integration/
│   │   ├── README.md
│   │   ├── stackit.docs.yaml    # <-- metadata for docs card
│   │   └── ...
│   └── ...
├── ci-scripts/
│   ├── aggregate_docs.py        # generates .mdx files + _meta.yml
│   └── sync-stackit-docs.sh     # CI: clone docs, copy files, PR
└── STACKIT-DOCS.md              # this file

stackit.docs.yaml Format

Each example must contain:

headline: Example Title
description: Short description of what the example demonstrates.
tags:
  - ske
  - kubernetes
  - terraform

Field	Required	Description
`headline`	Yes	Title displayed on the asset card
`description`	Yes	Brief summary (1-2 sentences) on the card
`tags`	Yes	Tags for filtering (shown on card, max 5)

Generated .mdx Format

Each stackit.docs.yaml is transformed into an .mdx file with frameworkAsset frontmatter:

---
title: SKE Azure Arc Integration
description: Terraform and CLI steps to connect a STACKIT SKE cluster to Azure Arc.
hideBreadcrumbs: true
sidebar:
  hidden: true
frameworkAsset:
  owner: Professional Services
  managed: true
  category: guide
  external: true
  recommended: true
  tags:
    - ske
    - azure
    - terraform
---

import { Card } from "@astrojs/starlight/components";

# SKE Azure Arc Integration

...

CI Process

flowchart TD
    A[Developer adds/updates<br>stackit.docs.yaml] --> B[PR to professional-services]
    B --> Merged{Merged to main?}
    Merged -->|Yes| C[GitHub Actions triggered]
    Merged -->|No| B
    C --> D[aggregate_docs.py<br>generates .mdx files + _meta.yml]
    D --> E[Clone docs-content repo]
    E --> F[Copy .mdx files to<br>assetcontainer/professional-services/]
    F --> G{Any file changes<br>vs current docs?}
    G -->|No| H[Exit: docs up to date]
    G -->|Yes| I[Create feature branch<br>autopr/sync-professional-service-examples]
    I --> J[Commit + push changes]
    J --> K[Create PR to docs-content]
    K --> L[Review and merge on<br>docs-content side]

Adding a New Example

Create a new directory under examples/
Add your Terraform code and README.md
Create stackit.docs.yaml with the required fields:

headline: My New Example
description: Demonstrates how to deploy X on STACKIT using Y.
tags:
  - ske
  - terraform
  - my-tag

Open a PR to this repository
Once merged, the CI will automatically:
- Generate .mdx asset files from all stackit.docs.yaml files
- Clone the docs-content repository
- Copy files to assetcontainer/professional-services/
- Open a PR if content has changed

Scripts

aggregate_docs.py

The Python script:

Scans examples/*/stackit.docs.yaml
Generates .mdx files with frameworkAsset frontmatter
Generates _meta.yml for the assetcontainer

Run locally to preview:

python3 ci-scripts/aggregate_docs.py
ls .generated-mdx/professional-services/
cat .generated-mdx/professional-services/ps-my-example.mdx

sync-stackit-docs.sh

The CI entrypoint:

Calls aggregate_docs.py to generate .mdx files
Clones stackitcloud/docs-content
Copies generated files to assetcontainer/professional-services/
Creates a PR if changes are detected

Environment Variables

Variable	Required	Description
`STACKIT_DOCS_TOKEN`	Yes	GitHub PAT with repo write permissions
`STACKIT_DOCS_REPO`	No	Target docs repo (default: `stackitcloud/docs-content`)

Manual Execution

export STACKIT_DOCS_TOKEN=<your-github-pat>
bash ci-scripts/sync-stackit-docs.sh

GitHub Actions Secret

To enable the CI workflow, add the following secret to the repository:

Secret name: STACKIT_DOCS_TOKEN
Value: GitHub Personal Access Token with repo scope

The workflow (.github/workflows/sync-stackit-docs.yaml) triggers on:

Every push to main that modifies examples/**/stackit.docs.yaml
Manual trigger via the GitHub Actions UI

5 KiB Raw Permalink Blame History