|
| 1 | +# GitHub Actions workflows |
| 2 | + |
| 3 | +This is the entry point for choosing and starting a pipeline. Workflow names link |
| 4 | +directly to their **Actions** pages; **source** links show the executable definition. |
| 5 | +The ten current repository workflows are listed below. Historical entries and |
| 6 | +GitHub-managed workflows are [listed separately](#other-entries-in-the-actions-sidebar). |
| 7 | + |
| 8 | +**A merge does not deploy the Configurator.** Configurator provisioning and |
| 9 | +application releases are manual and currently target development, not production. |
| 10 | +Starting a workflow is not the same as approving its protected deployment job. |
| 11 | + |
| 12 | +## Which workflow do I need? |
| 13 | + |
| 14 | +| Task | Workflow | |
| 15 | +| --- | --- | |
| 16 | +| Check Accelerator changes without provisioning resources | **Validate** | |
| 17 | +| Check Configurator, catalogue, database, browser and operator-IaC changes | **Validate Configurator** | |
| 18 | +| Test Assistant answers against the real model | **Assistant live regression** | |
| 19 | +| Deploy a new Configurator version, including API/UI and Runner | **Configurator Release**, not Publish Release | |
| 20 | +| Change the Configurator's own state storage, managed services or CF identities | **Configurator Bootstrap**, **Platform** or **Runtime** | |
| 21 | +| Exercise a real Accelerator deployment and cleanup | **Verify Deployment** | |
| 22 | +| Publish an Accelerator GitHub release after real deployment verification | **Publish Release** | |
| 23 | +| Compare configured machine flavors with the live STACKIT catalogue | **Validate STACKIT Flavors** | |
| 24 | + |
| 25 | +## Current repository workflows |
| 26 | + |
| 27 | +**Automatic** describes repository events, not a manual click. **Reusable** means |
| 28 | +another workflow can call it through `workflow_call`; it is not a separate UI |
| 29 | +approval. All ten definitions expose `workflow_dispatch`, but permissions, |
| 30 | +branch restrictions, operator switches and environment protection still apply. |
| 31 | + |
| 32 | +| Workflow and definition | Purpose | Automatic start | Manual start in Actions | Reusable / effects | |
| 33 | +| --- | --- | --- | --- | --- | |
| 34 | +| [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 | |
| 35 | +| [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 | |
| 36 | +| [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 | |
| 37 | +| [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`. | |
| 38 | +| [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. | |
| 39 | +| [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. | |
| 40 | +| [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 | |
| 41 | +| [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 | |
| 42 | +| [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. | |
| 43 | +| [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. | |
| 44 | + |
| 45 | +The exact Configurator path filter is in the linked YAML. A skipped |
| 46 | +Accelerator-only job on a Configurator PR is intentional, not a deployment. |
| 47 | +Do not make a path-filtered job a globally required check without ensuring that |
| 48 | +it reports a result for every relevant PR. |
| 49 | + |
| 50 | +## Start a workflow in the GitHub UI |
| 51 | + |
| 52 | +1. Open the repository's [Actions tab](https://github.com/stackitcloud/stackit-landing-zone/actions) |
| 53 | + or the workflow link in the table. |
| 54 | +2. Select the workflow, then **Run workflow**. Use **main** for ordinary |
| 55 | + operational runs; a branch dropdown does not override job/environment guards. |
| 56 | +3. Fill in the inputs below and start the run. A missing button can indicate |
| 57 | + insufficient repository permissions, disabled Actions, or a definition without |
| 58 | + `workflow_dispatch` on the default branch. Old sidebar entries are not proof |
| 59 | + that a workflow still exists. |
| 60 | +4. Follow the new run. For a protected job, an authorized reviewer must use |
| 61 | + **Review deployments**, select the environment and approve it. PR merge |
| 62 | + approval/admin bypass does **not** approve a deployment. |
| 63 | +5. Check the complete run, not only dispatch success or the first green job. |
| 64 | + An accepted dispatch can still have skipped jobs if a gate is disabled. |
| 65 | + |
| 66 | +### Manual start and inputs |
| 67 | + |
| 68 | +| Workflow | Inputs and prerequisites | |
| 69 | +| --- | --- | |
| 70 | +| Validate / Validate Configurator / Validate STACKIT Flavors | No workflow inputs | |
| 71 | +| 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. | |
| 72 | +| 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. | |
| 73 | +| Publish Release | `version` is required. Select `main`; other branches do not pass the verification-job guard. | |
| 74 | +| Configurator Bootstrap | `root=bootstrap` by default, or `backend`; `apply=false` by default. Apply uses `lzc-dev-bootstrap-apply`. | |
| 75 | +| Configurator Platform | `root=platform`; `apply=false` by default. Requires the platform operator switch above; Apply uses `lzc-dev-platform-apply`. | |
| 76 | +| Configurator Runtime | `root=runtime`; `apply=false` by default. Requires the runtime operator switch above; Apply uses `lzc-dev-runtime-apply`. | |
| 77 | +| 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. | |
| 78 | + |
| 79 | +For the normal Configurator deployment: select **Configurator Release**, `main`, |
| 80 | +leave **build_only unchecked** and **release_run_id empty**, then approve |
| 81 | +`lzc-dev-release` when prompted. This deploys development, not a new production |
| 82 | +environment. See the [release runbook](../landing-zone-configurator/deploy/cloud-foundry/README.md#manual-development-release-in-github) |
| 83 | +for promotion and failure handling. |
| 84 | + |
| 85 | +Bootstrap, Platform, Runtime and Release reject **Re-run jobs** attempts: |
| 86 | +start a **new Run workflow** instead. Infrastructure Apply uses the reviewed |
| 87 | +encrypted Plan from that same run, not an older run's Plan. A fresh promotion run |
| 88 | +can reuse an existing qualified release build; do not confuse this with re-running |
| 89 | +the original deployment. Failed qualifications remain failures. |
| 90 | + |
| 91 | +All four mutating Configurator workflows share the |
| 92 | +`configurator-lzc-dev-mutation` queue and do not cancel an active mutation. |
| 93 | +Assistant model runs have their own serialized queue. Never start parallel local |
| 94 | +cloud writes to bypass these safeguards. |
| 95 | + |
| 96 | +### CLI equivalent |
| 97 | + |
| 98 | +From a terminal authenticated with GitHub CLI, for example to check the Configurator: |
| 99 | + |
| 100 | +```sh |
| 101 | +gh workflow run validate-configurator.yml \ |
| 102 | + --repo stackitcloud/stackit-landing-zone --ref main |
| 103 | +``` |
| 104 | + |
| 105 | +Use the workflow filename from the **source** link to select another workflow. |
| 106 | +Pass its inputs using `-f name=value`; this has the same effects and authorization |
| 107 | +requirements as the UI. For example, `-f root=backend -f apply=false` selects a |
| 108 | +Plan-only Bootstrap run. Do not put credentials, raw Plans or state in inputs. |
| 109 | +`gh run list --repo stackitcloud/stackit-landing-zone --workflow validate-configurator.yml --limit 5` |
| 110 | +shows recent runs; `gh run watch RUN_ID --repo stackitcloud/stackit-landing-zone` |
| 111 | +watches one run. Dispatch success alone does not mean its jobs succeeded. |
| 112 | + |
| 113 | +## Other entries in the Actions sidebar |
| 114 | + |
| 115 | +GitHub retains workflow history after files are removed and also shows workflows |
| 116 | +managed by GitHub itself. These are not additional current repository definitions. |
| 117 | + |
| 118 | +| Sidebar entry | Where it comes from | How it starts / what to do | |
| 119 | +| --- | --- | --- | |
| 120 | +| [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. | |
| 121 | +| [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`. | |
| 122 | +| 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 | |
| 123 | +| 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. | |
| 124 | + |
| 125 | +## Maintaining this catalogue |
| 126 | + |
| 127 | +Update this page when changing a workflow's name, triggers, inputs, branch guards, |
| 128 | +environment approvals or operational effects. Keep reusable calls distinct from |
| 129 | +automatic push/PR triggers. Workflow YAML and the linked operator runbooks are the |
| 130 | +source of truth; this catalogue is not deployment authorization. |
| 131 | + |
| 132 | +Related references: [contributing](../CONTRIBUTING.md), |
| 133 | +[Configurator development](../landing-zone-configurator/docs/development.md), |
| 134 | +[operator CI and environment gates](../landing-zone-configurator/infra/ci/README.md). |
0 commit comments