lweberru · Oct 17, 2026 · Oct 17, 2026
@@ -96,6 +96,11 @@ Do not share execution credentials with the inference-only `assistant-tests`
 environment. Configurator provisioning and deployment remain manual; production
 setup is a separate task.
 
+The [workflow catalogue](docs/workflows.md) lists all pipelines, automatic/manual
+triggers and UI start instructions. Update it when changing workflow names,
+triggers, inputs or operational gates; keep deployment authorization separate
+from PR approval.
+
 ### Terraform conventions
 
 Follow the full [Terraform style guide](docs/terraform-style.md) alongside the

@@ -29,6 +29,7 @@ filled manually and use a separate backend/state.
 - [Configurator Architecture](landing-zone-configurator/docs/architecture.md)
 - [Configurator User Guide](landing-zone-configurator/docs/user-guide.md)
 - [Configurator Development](landing-zone-configurator/docs/development.md)
+- [GitHub Actions Workflows](docs/workflows.md) - all pipelines, automatic/manual triggers, UI start instructions, inputs and deployment effects
 
 ## 🤝 Contributing
 

@@ -0,0 +1,134 @@
+# GitHub Actions workflows
+
+This is the entry point for choosing and starting a pipeline. Workflow names link
+directly to their **Actions** pages; **source** links show the executable definition.
+The ten current repository workflows are listed below. Historical entries and
+GitHub-managed workflows are [listed separately](#other-entries-in-the-actions-sidebar).
+
+**A merge does not deploy the Configurator.** Configurator provisioning and
+application releases are manual and currently target development, not production.
+Starting a workflow is not the same as approving its protected deployment job.
+
+## Which workflow do I need?
+
+| Task | Workflow |
+| --- | --- |
+| Check Accelerator changes without provisioning resources | **Validate** |
+| Check Configurator, catalogue, database, browser and operator-IaC changes | **Validate Configurator** |
+| Test Assistant answers against the real model | **Assistant live regression** |
+| Deploy a new Configurator version, including API/UI and Runner | **Configurator Release**, not Publish Release |
+| Change the Configurator's own state storage, managed services or CF identities | **Configurator Bootstrap**, **Platform** or **Runtime** |
+| Exercise a real Accelerator deployment and cleanup | **Verify Deployment** |
+| Publish an Accelerator GitHub release after real deployment verification | **Publish Release** |
+| Compare configured machine flavors with the live STACKIT catalogue | **Validate STACKIT Flavors** |
+
+## Current repository workflows
+
+**Automatic** describes repository events, not a manual click. **Reusable** means
+another workflow can call it through `workflow_call`; it is not a separate UI
+approval. All ten definitions expose `workflow_dispatch`, but permissions,
+branch restrictions, operator switches and environment protection still apply.
+
+| Workflow and definition | Purpose | Automatic start | Manual start in Actions | Reusable / effects |
+| --- | --- | --- | --- | --- |
+| [Validate](https://github.com/stackitcloud/stackit-landing-zone/actions/workflows/validate.yml) · [source](../.github/workflows/validate.yml) | Accelerator formatting, lint, validation and mocked configuration tests | Every PR; push to `main`. Heavy jobs run only for relevant native/tooling changes; manual dispatch forces them to run. | **Run workflow**, no inputs | No real infrastructure provisioning |
+| [Validate Configurator](https://github.com/stackitcloud/stackit-landing-zone/actions/workflows/validate-configurator.yml) · [source](../.github/workflows/validate-configurator.yml) | HCL/catalogue freshness, app lint/build/unit tests, PostgreSQL, desktop/mobile browser tests and six mocked operator-IaC roots | PRs and pushes to `main` affecting `landing-zone-configurator/**`, `src/**` or its explicitly listed workflow files | **Run workflow**, no inputs; manually runs without the path filter | No real infrastructure provisioning or real-model qualification |
+| [Validate STACKIT Flavors](https://github.com/stackitcloud/stackit-landing-zone/actions/workflows/validate-stackit-flavors.yml) · [source](../.github/workflows/validate-stackit-flavors.yml) | Compare configured flavors against live STACKIT SKUs | Mondays, **05:17 UTC**, on the default branch (`17 5 * * 1`); scheduled runs may be delayed by GitHub | **Run workflow**, no inputs | Reads an external catalogue; no deployment |
+| [Assistant live regression](https://github.com/stackitcloud/stackit-landing-zone/actions/workflows/assistant-live.yml) · [source](../.github/workflows/assistant-live.yml) | Repeated factual cases and a continuous multi-topic dialogue using real Model Serving | None on push/PR; called by a fresh Configurator Release | **Run workflow** with topic and repetition count | Reusable by **Configurator Release**. Inference costs; no cloud Plan/Apply. Uses `assistant-tests`. |
+| [Verify Deployment](https://github.com/stackitcloud/stackit-landing-zone/actions/workflows/verify-deployment.yml) · [source](../.github/workflows/verify-deployment.yml) | Real Accelerator Plan, Apply and cleanup in the configured test organization | None on push/PR; called by Publish Release | **Run workflow** with a variable-file path | Reusable by **Publish Release**. **Creates and destroys real cloud resources** using `terraform-plan`. Retains the governance folder skeleton; failed cleanup can leave resources. |
+| [Publish Release](https://github.com/stackitcloud/stackit-landing-zone/actions/workflows/publish-release.yml) · [source](../.github/workflows/publish-release.yml) | Verify the Accelerator, then create a GitHub release/tag with source archives and provenance | None; not triggered by pushing a tag | **Run workflow** on `main`, with a version | Calls **Verify Deployment** first: **real cloud changes and costs**, followed by GitHub release publication. Does not deploy the Configurator. |
+| [Configurator Bootstrap](https://github.com/stackitcloud/stackit-landing-zone/actions/workflows/configurator-bootstrap.yml) · [source](../.github/workflows/configurator-bootstrap.yml) | Plan the workload-state bucket/access (`bootstrap`) or its versioning (`backend`) | None | **Run workflow** on `main`; choose root and optionally Apply | Real backend/credential access for Plan; `apply=true` enables cloud changes after protected environment approval |
+| [Configurator Platform](https://github.com/stackitcloud/stackit-landing-zone/actions/workflows/configurator-platform.yml) · [source](../.github/workflows/configurator-platform.yml) | Plan shared Configurator services: CF organization, database, Secrets Manager, artifact storage and model token | None | **Run workflow** on `main`; optionally Apply; requires `LZC_PLATFORM_CI_ENABLED=true` | Real backend/credential access for Plan; optional approved cloud Apply |
+| [Configurator Runtime](https://github.com/stackitcloud/stackit-landing-zone/actions/workflows/configurator-runtime.yml) · [source](../.github/workflows/configurator-runtime.yml) | Plan CF space/roles and database/Secrets runtime users | None | **Run workflow** on `main`; optionally Apply; requires `LZC_RUNTIME_CI_ENABLED=true` | Real backend/credential access for Plan; optional approved cloud Apply. Does not publish application code. |
+| [Configurator Release](https://github.com/stackitcloud/stackit-landing-zone/actions/workflows/configurator-release.yml) · [source](../.github/workflows/configurator-release.yml) | Qualify, build and package API/UI and Runner together, or promote an existing qualified build | None; a merge does not start it | **Run workflow** on `main`; choose build-only, new release or promotion; requires `LZC_RELEASE_CI_ENABLED=true` | Fresh builds call **Assistant live regression** and publish a protected buildpack tag. Unless build-only, deploys development after `lzc-dev-release` approval, including migrations and runtime checks. |
+
+The exact Configurator path filter is in the linked YAML. A skipped
+Accelerator-only job on a Configurator PR is intentional, not a deployment.
+Do not make a path-filtered job a globally required check without ensuring that
+it reports a result for every relevant PR.
+
+## Start a workflow in the GitHub UI
+
+1. Open the repository's [Actions tab](https://github.com/stackitcloud/stackit-landing-zone/actions)
+   or the workflow link in the table.
+2. Select the workflow, then **Run workflow**. Use **main** for ordinary
+   operational runs; a branch dropdown does not override job/environment guards.
+3. Fill in the inputs below and start the run. A missing button can indicate
+   insufficient repository permissions, disabled Actions, or a definition without
+   `workflow_dispatch` on the default branch. Old sidebar entries are not proof
+   that a workflow still exists.
+4. Follow the new run. For a protected job, an authorized reviewer must use
+   **Review deployments**, select the environment and approve it. PR merge
+   approval/admin bypass does **not** approve a deployment.
+5. Check the complete run, not only dispatch success or the first green job.
+   An accepted dispatch can still have skipped jobs if a gate is disabled.
+
+### Manual start and inputs
+
+| Workflow | Inputs and prerequisites |
+| --- | --- |
+| Validate / Validate Configurator / Validate STACKIT Flavors | No workflow inputs |
+| Assistant live regression | `topic=all` by default, or a knowledge topic ID; `repetitions=2` by default, supported range 1-3. The continuous dialogue also runs for a topic-selected qualification. The protected `assistant-tests` environment currently permits `main` and the explicitly allowed legacy Configurator feature branch. |
+| Verify Deployment | `var_file=config/hub-and-spoke-firewall.tfvars` by default; must be an existing relative path below `src/`. Manual runs use the selected revision. The reusable call also accepts `ref`; that is not a dispatch input. |
+| Publish Release | `version` is required. Select `main`; other branches do not pass the verification-job guard. |
+| Configurator Bootstrap | `root=bootstrap` by default, or `backend`; `apply=false` by default. Apply uses `lzc-dev-bootstrap-apply`. |
+| Configurator Platform | `root=platform`; `apply=false` by default. Requires the platform operator switch above; Apply uses `lzc-dev-platform-apply`. |
+| Configurator Runtime | `root=runtime`; `apply=false` by default. Requires the runtime operator switch above; Apply uses `lzc-dev-runtime-apply`. |
+| Configurator Release | `build_only=false` by default; `release_run_id` empty means fresh qualification/build. Set `build_only=true` to build without CF deployment; real-model calls and protected tag publication still occur. To promote an existing qualified build, leave build-only unchecked and enter its numeric run ID; the retained artifact/tag must remain valid. |
+
+For the normal Configurator deployment: select **Configurator Release**, `main`,
+leave **build_only unchecked** and **release_run_id empty**, then approve
+`lzc-dev-release` when prompted. This deploys development, not a new production
+environment. See the [release runbook](../landing-zone-configurator/deploy/cloud-foundry/README.md#manual-development-release-in-github)
+for promotion and failure handling.
+
+Bootstrap, Platform, Runtime and Release reject **Re-run jobs** attempts:
+start a **new Run workflow** instead. Infrastructure Apply uses the reviewed
+encrypted Plan from that same run, not an older run's Plan. A fresh promotion run
+can reuse an existing qualified release build; do not confuse this with re-running
+the original deployment. Failed qualifications remain failures.
+
+All four mutating Configurator workflows share the
+`configurator-lzc-dev-mutation` queue and do not cancel an active mutation.
+Assistant model runs have their own serialized queue. Never start parallel local
+cloud writes to bypass these safeguards.
+
+### CLI equivalent
+
+From a terminal authenticated with GitHub CLI, for example to check the Configurator:
+
+```sh
+gh workflow run validate-configurator.yml \
+  --repo stackitcloud/stackit-landing-zone --ref main
+```
+
+Use the workflow filename from the **source** link to select another workflow.
+Pass its inputs using `-f name=value`; this has the same effects and authorization
+requirements as the UI. For example, `-f root=backend -f apply=false` selects a
+Plan-only Bootstrap run. Do not put credentials, raw Plans or state in inputs.
+`gh run list --repo stackitcloud/stackit-landing-zone --workflow validate-configurator.yml --limit 5`
+shows recent runs; `gh run watch RUN_ID --repo stackitcloud/stackit-landing-zone`
+watches one run. Dispatch success alone does not mean its jobs succeeded.
+
+## Other entries in the Actions sidebar
+
+GitHub retains workflow history after files are removed and also shows workflows
+managed by GitHub itself. These are not additional current repository definitions.
+
+| Sidebar entry | Where it comes from | How it starts / what to do |
+| --- | --- | --- |
+| [Terraform Plan](https://github.com/stackitcloud/stackit-landing-zone/actions/workflows/terraform-plan.yml) | Historical workflow; its YAML no longer exists on `main` | Not a current manual entry point. Use the current inventory above; an old run or GitHub's workflow-state label does not restore the deleted definition. |
+| [Terraform Apply](https://github.com/stackitcloud/stackit-landing-zone/actions/workflows/terraform-apply.yml) | Historical workflow; its YAML no longer exists on `main` | Do not rerun historical cloud writes as a substitute for an authorized current Plan/Apply flow. No current `Run workflow` definition on `main`. |
+| Copilot cloud agent | GitHub-managed agent workflow, not YAML in this repository | Starts through GitHub's Copilot agent task interface, subject to repository policy and access; not via our `workflow_dispatch` inputs |
+| Dependabot Updates | GitHub-managed update jobs configured in [dependabot.yml](../.github/dependabot.yml) | Weekly on Sundays for Terraform providers and GitHub Actions; GitHub's Dependabot UI manages update checks. Resulting PRs go through normal repository validation, not automatic deployment. |
+
+## Maintaining this catalogue
+
+Update this page when changing a workflow's name, triggers, inputs, branch guards,
+environment approvals or operational effects. Keep reusable calls distinct from
+automatic push/PR triggers. Workflow YAML and the linked operator runbooks are the
+source of truth; this catalogue is not deployment authorization.
+
+Related references: [contributing](../CONTRIBUTING.md),
+[Configurator development](../landing-zone-configurator/docs/development.md),
+[operator CI and environment gates](../landing-zone-configurator/infra/ci/README.md).
@@ -53,14 +53,10 @@ replace native progress with invented percentages or expose raw machine UI,
 saved-plan JSON or state. Assistant acceptance and output viewing grant no
 execution permission.
 
-| Workflow | Trigger and purpose |
-| --- | --- |
-| Validate | Every PR and main push; required Accelerator check names remain present, with change-aware execution |
-| Validate Configurator | Relevant PRs/main pushes or manual dispatch; catalogue, app, browser, database and mock-IaC checks |
-| Assistant live qualification | Manual/reusable; synthetic inference with a dedicated test token, no execution credentials |
-| Verify Deployment / Publish Release | Manual Accelerator cloud verification/release; not ordinary PR validation |
-| Configurator Bootstrap / Platform / Runtime | Manual main-branch plan, optional separately approved Apply |
-| Configurator Release | Manual qualified build/promotion and optional development deployment |
+The repository-wide [workflow catalogue](../../docs/workflows.md) is the central
+table for all pipelines, automatic/manual triggers, reusable calls, inputs and
+GitHub UI start instructions. Update it alongside workflow changes rather than
+maintaining a second partial inventory here.
 
 Source merge does not dispatch deployment. Never put customer credentials,
 state, private inventories or raw Plan output in issues, chat or test artifacts.

@@ -1,5 +1,9 @@
 # OpenTofu in GitHub Actions
 
+Die zentrale [Workflow-Uebersicht](../../../docs/workflows.md) beschreibt alle
+Pipelines, automatische und manuelle Ausloeser, Eingaben und den Start im
+GitHub-UI. Diese Seite vertieft die Operator- und Freigabevertraege.
+
 Die ausführbaren Deployments stehen direkt in den Workflows:
 
 - [Configurator Bootstrap](../../../.github/workflows/configurator-bootstrap.yml): `bootstrap` oder `backend`.