From 545ecee5e792c8cd40b2befe92ca239f489c3e24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lukas=20Weberru=C3=9F?= Date: Sat, 17 Oct 2026 09:13:01 +0000 Subject: [PATCH] docs: catalogue GitHub workflows and manual start options Document all ten current workflows, their triggers and operational effects, UI/CLI dispatch, inputs, approvals and separate historical/GitHub-managed entries. Link the catalogue from public and contributor entry points without changing workflows. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 5 + README.md | 1 + docs/workflows.md | 134 ++++++++++++++++++ landing-zone-configurator/docs/development.md | 12 +- landing-zone-configurator/infra/ci/README.md | 4 + 5 files changed, 148 insertions(+), 8 deletions(-) create mode 100644 docs/workflows.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cea0b92..3cbd85f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/README.md b/README.md index f2cccc3..33cbe87 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/workflows.md b/docs/workflows.md new file mode 100644 index 0000000..fc5318a --- /dev/null +++ b/docs/workflows.md @@ -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). diff --git a/landing-zone-configurator/docs/development.md b/landing-zone-configurator/docs/development.md index d04281e..46e3d80 100644 --- a/landing-zone-configurator/docs/development.md +++ b/landing-zone-configurator/docs/development.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. diff --git a/landing-zone-configurator/infra/ci/README.md b/landing-zone-configurator/infra/ci/README.md index 983fd2a..31b9998 100644 --- a/landing-zone-configurator/infra/ci/README.md +++ b/landing-zone-configurator/infra/ci/README.md @@ -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`.