Simone/local-ci-cd-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor documentation and analysis in final master plan, opus47 analysis, and opus47 review of GPT-5.5

Browse Source 
- Updated the final master plan to improve clarity and consistency in the status of various capabilities, including fixes and enhancements made as of 2026-05-12.
- Revised the opus47 analysis to provide a more structured overview of the system's production readiness, including detailed coverage of OWASP Top 10 risks and operational gaps.
- Enhanced the opus47 review of GPT-5.5 by clarifying severity ratings and rationales for various items, while adding new high-severity items that were previously overlooked.
This commit is contained in:
Simone
2026-05-13 00:08:19 +02:00
parent 5d1b47e943
commit 3592dcab78
13 changed files with 350 additions and 343 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/WORKFLOW-AUTHORING.md
+87 -80
View File
@@ -8,23 +8,30 @@
## Table of Contents
1. [System Overview](#1-system-overview)
2. [Runner Labels](#2-runner-labels)
3. [Shell Requirement](#3-shell-requirement)
4. [Environment Variables (Injected by Runner)](#4-environment-variables-injected-by-runner)
5. [Invoke-CIJob.ps1 Parameter Reference](#5-invoke-cijobps1-parameter-reference)
6. [URL Conventions](#6-url-conventions)
7. [Artifact Path Convention](#7-artifact-path-convention)
8. [Workflow Patterns](#8-workflow-patterns)
- [8.1 Windows build (host-clone mode)](#81-windows-build-host-clone-mode)
- [8.2 Linux build (host-clone mode)](#82-linux-build-host-clone-mode)
- [8.3 Windows build (UseGitClone mode)](#83-windows-build-usegitclone-mode)
- [8.4 Linux build (UseGitClone mode)](#84-linux-build-usegitclone-mode)
- [8.5 PSScriptAnalyzer lint](#85-psscriptanalyzer-lint)
- [8.6 Matrix build (multiple configs)](#86-matrix-build-multiple-configs)
9. [Checkout Step](#9-checkout-step)
10. [Timeouts](#10-timeouts)
11. [Common Mistakes](#11-common-mistakes)
- [Workflow Authoring Reference](#workflow-authoring-reference)
- [Table of Contents](#table-of-contents)
- [1. System Overview](#1-system-overview)
- [2. Runner Labels](#2-runner-labels)
- [3. Shell Requirement](#3-shell-requirement)
- [4. Environment Variables (Injected by Runner)](#4-environment-variables-injected-by-runner)
- [5. Invoke-CIJob.ps1 Parameter Reference](#5-invoke-cijobps1-parameter-reference)
- [Mandatory parameters](#mandatory-parameters)
- [Optional parameters](#optional-parameters)
- [6. URL Conventions](#6-url-conventions)
- [Host-clone mode (default, no `-UseGitClone`)](#host-clone-mode-default-no--usegitclone)
- [UseGitClone mode (`-UseGitClone`)](#usegitclone-mode--usegitclone)
- [Quick reference](#quick-reference)
- [7. Artifact Path Convention](#7-artifact-path-convention)
- [8. Workflow Patterns](#8-workflow-patterns)
- [8.1 Windows build (host-clone mode)](#81-windows-build-host-clone-mode)
- [8.2 Linux build (host-clone mode)](#82-linux-build-host-clone-mode)
- [8.3 Windows build (UseGitClone mode)](#83-windows-build-usegitclone-mode)
- [8.4 Linux build (UseGitClone mode)](#84-linux-build-usegitclone-mode)
- [8.5 PSScriptAnalyzer lint](#85-psscriptanalyzer-lint)
- [8.6 Matrix build (multiple configs)](#86-matrix-build-multiple-configs)
- [9. Checkout Step](#9-checkout-step)
- [10. Timeouts](#10-timeouts)
- [11. Common Mistakes](#11-common-mistakes)
---
@@ -50,12 +57,12 @@ Supported guest OS: Windows Server 2025 / 2022 (WinRM transport), Ubuntu 24.04 (
## 2. Runner Labels
| Label | Configured as | Use for |
| ---------------- | ---------------- | ----------------------------------- |
| `windows-build` | `windows-build:host` | Windows VM builds, Windows-only tools |
| `linux-build` | `linux-build:host` | Linux VM builds (cross-compile, GCC/Clang) |
| `dotnet` | `dotnet:host` | Alias for windows-build (legacy) |
| `msbuild` | `msbuild:host` | Alias for windows-build (legacy) |
| Label | Configured as | Use for |
| --------------- | -------------------- | ------------------------------------------ |
| `windows-build` | `windows-build:host` | Windows VM builds, Windows-only tools |
| `linux-build` | `linux-build:host` | Linux VM builds (cross-compile, GCC/Clang) |
| `dotnet` | `dotnet:host` | Alias for windows-build (legacy) |
| `msbuild` | `msbuild:host` | Alias for windows-build (legacy) |
Both `windows-build` and `linux-build` run on the same physical host. Only the
template VM used differs. Use `windows-build` unless you specifically need a Linux
@@ -91,14 +98,14 @@ required runtime and may not be present on the host.
These variables are automatically available in every job step. Do not redeclare them
in the workflow unless you need to override the default.
| Variable | Value (default) | Description |
| ---------------------------- | ---------------------------------------------------- | --------------------------------------- |
| `GITEA_CI_TEMPLATE_PATH` | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx` | Windows 2025 template VMX path |
| `GITEA_CI_LINUX_TEMPLATE_PATH` | `F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx` | Ubuntu 24.04 template VMX path |
| `GITEA_CI_CLONE_BASE_DIR` | `F:\CI\BuildVMs` | Directory for ephemeral VM clones |
| `GITEA_CI_ARTIFACT_DIR` | `F:\CI\Artifacts` | Root directory for job artifacts |
| `GITEA_CI_GUEST_CRED_TARGET` | `BuildVMGuest` | Credential Manager target for guest VM |
| `GITEA_CI_SSH_KEY_PATH` | `F:\CI\keys\ci_linux` | SSH private key for Linux guest access |
| Variable | Value (default) | Description |
| ------------------------------ | --------------------------------------------------- | -------------------------------------- |
| `GITEA_CI_TEMPLATE_PATH` | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx` | Windows 2025 template VMX path |
| `GITEA_CI_LINUX_TEMPLATE_PATH` | `F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx` | Ubuntu 24.04 template VMX path |
| `GITEA_CI_CLONE_BASE_DIR` | `F:\CI\BuildVMs` | Directory for ephemeral VM clones |
| `GITEA_CI_ARTIFACT_DIR` | `F:\CI\Artifacts` | Root directory for job artifacts |
| `GITEA_CI_GUEST_CRED_TARGET` | `BuildVMGuest` | Credential Manager target for guest VM |
| `GITEA_CI_SSH_KEY_PATH` | `F:\CI\keys\ci_linux` | SSH private key for Linux guest access |
Invoke-CIJob.ps1 reads `GITEA_CI_TEMPLATE_PATH` and `GITEA_CI_CLONE_BASE_DIR`
automatically if `-TemplatePath` and `-CloneBaseDir` are not passed explicitly.
@@ -111,33 +118,33 @@ Script location (fixed on host): `N:\Code\Workspace\Local-CI-CD-System\scripts\I
### Mandatory parameters
| Parameter | Type | Description |
| ----------- | ------ | --------------------------------------------------------------- |
| `-JobId` | string | Unique job ID. Use `${{ github.run_id }}` or `run_id-run_attempt`. |
| `-RepoUrl` | string | Git URL of the repository to clone/build. See Section 6. |
| `-Branch` | string | Branch to build. Use `${{ github.ref_name }}`. |
| Parameter | Type | Description |
| ---------- | ------ | ------------------------------------------------------------------ |
| `-JobId` | string | Unique job ID. Use `${{ github.run_id }}` or `run_id-run_attempt`. |
| `-RepoUrl` | string | Git URL of the repository to clone/build. See Section 6. |
| `-Branch` | string | Branch to build. Use `${{ github.ref_name }}`. |
### Optional parameters
| Parameter | Type | Default | Description |
| ------------------------ | ------ | --------------------------- | -------------------------------------------------------------- |
| `-Commit` | string | `''` | Specific commit SHA. Use `${{ github.sha }}`. Empty = HEAD. |
| `-TemplatePath` | string | `$env:GITEA_CI_TEMPLATE_PATH` | Full path to template VMX. |
| `-SnapshotName` | string | `BaseClean` | Template snapshot name to clone from. |
| `-GuestOS` | string | `Auto` | `Windows`, `Linux`, or `Auto` (detected from VMX guestOS field). |
| `-BuildCommand` | string | `''` | Shell command to run inside VM. Empty = `dotnet build`. |
| `-GuestArtifactSource` | string | `dist` | Path inside VM guest from which artifacts are collected. |
| `-Submodules` | switch | off | Pass to clone with `--recurse-submodules`. |
| `-UseGitClone` | switch | off | Skip host-side clone; let the guest VM clone directly via HTTPS. |
| `-GiteaCredentialTarget` | string | `GiteaPAT` | Credential Manager target for Gitea PAT (UseGitClone only). |
| `-GuestCredentialTarget` | string | `BuildVMGuest` | Credential Manager target for Windows guest VM login. |
| `-SshKeyPath` | string | `F:\CI\keys\ci_linux` | SSH key for Linux guest (ignored for Windows). |
| `-SshUser` | string | `ci_build` | SSH username for Linux guest (ignored for Windows). |
| `-CloneBaseDir` | string | `$env:GITEA_CI_CLONE_BASE_DIR` | Directory for VM clone files. |
| `-ArtifactBaseDir` | string | `F:\CI\Artifacts` | Root artifact directory on host. |
| `-VMIPAddress` | string | `''` | Override guest IP. Empty = auto-detected via vmrun. |
| `-LogDir` | string | `F:\CI\Logs` | Directory for per-job transcripts and JSONL logs. |
| `-LogRetentionDays` | int | `30` | Days before log directories are purged. `0` = disabled. |
| Parameter | Type | Default | Description |
| ------------------------ | ------ | ------------------------------ | ---------------------------------------------------------------- |
| `-Commit` | string | `''` | Specific commit SHA. Use `${{ github.sha }}`. Empty = HEAD. |
| `-TemplatePath` | string | `$env:GITEA_CI_TEMPLATE_PATH` | Full path to template VMX. |
| `-SnapshotName` | string | `BaseClean` | Template snapshot name to clone from. |
| `-GuestOS` | string | `Auto` | `Windows`, `Linux`, or `Auto` (detected from VMX guestOS field). |
| `-BuildCommand` | string | `''` | Shell command to run inside VM. Empty = `dotnet build`. |
| `-GuestArtifactSource` | string | `dist` | Path inside VM guest from which artifacts are collected. |
| `-Submodules` | switch | off | Pass to clone with `--recurse-submodules`. |
| `-UseGitClone` | switch | off | Skip host-side clone; let the guest VM clone directly via HTTPS. |
| `-GiteaCredentialTarget` | string | `GiteaPAT` | Credential Manager target for Gitea PAT (UseGitClone only). |
| `-GuestCredentialTarget` | string | `BuildVMGuest` | Credential Manager target for Windows guest VM login. |
| `-SshKeyPath` | string | `F:\CI\keys\ci_linux` | SSH key for Linux guest (ignored for Windows). |
| `-SshUser` | string | `ci_build` | SSH username for Linux guest (ignored for Windows). |
| `-CloneBaseDir` | string | `$env:GITEA_CI_CLONE_BASE_DIR` | Directory for VM clone files. |
| `-ArtifactBaseDir` | string | `F:\CI\Artifacts` | Root artifact directory on host. |
| `-VMIPAddress` | string | `''` | Override guest IP. Empty = auto-detected via vmrun. |
| `-LogDir` | string | `F:\CI\Logs` | Directory for per-job transcripts and JSONL logs. |
| `-LogRetentionDays` | int | `30` | Days before log directories are purged. `0` = disabled. |
Exit codes: `0` = success, `1` = failure (VM is always destroyed regardless).
@@ -173,11 +180,11 @@ https://gitea.emulab.it/<owner>/<repo>.git
### Quick reference
| Mode | RepoUrl to use |
| ----------------- | ---------------------------------------------------------- |
| Default (Windows) | `ssh://gitea-ci/<owner>/<repo>.git` |
| Default (Linux) | `ssh://gitea-ci/<owner>/<repo>.git` |
| UseGitClone | `https://gitea.emulab.it/<owner>/<repo>.git` |
| Mode | RepoUrl to use |
| ----------------- | -------------------------------------------- |
| Default (Windows) | `ssh://gitea-ci/<owner>/<repo>.git` |
| Default (Linux) | `ssh://gitea-ci/<owner>/<repo>.git` |
| UseGitClone | `https://gitea.emulab.it/<owner>/<repo>.git` |
---
@@ -537,13 +544,13 @@ The CI scripts are at a fixed path on the runner host and do not need a checkout
## 10. Timeouts
| Build type | Recommended `timeout-minutes` |
| --------------------------- | ----------------------------- |
| Windows build (typical) | 90 |
| Windows build (large/slow) | 120 |
| Linux build (typical) | 60 |
| Lint / static analysis | 10 |
| Template provisioning | 180 |
| Build type | Recommended `timeout-minutes` |
| -------------------------- | ----------------------------- |
| Windows build (typical) | 90 |
| Windows build (large/slow) | 120 |
| Linux build (typical) | 60 |
| Lint / static analysis | 10 |
| Template provisioning | 180 |
The runner-level timeout is `2h` (from `runner/config.yaml`). Keep job timeouts
below that value. If a job timeout fires, the VM may not be cleanly destroyed —
@@ -553,16 +560,16 @@ the cleanup task `Cleanup-OrphanedBuildVMs.ps1` handles these cases.
## 11. Common Mistakes
| Mistake | Correct approach |
| ------- | ---------------- |
| `shell: pwsh` | Use `shell: powershell` (PS 5.1, not Core) |
| SSH alias URL with `-UseGitClone` | Use `https://gitea.emulab.it/...` for UseGitClone; SSH alias is host-only |
| HTTPS URL without `-UseGitClone` | SSH alias `ssh://gitea-ci/...` for host-clone mode |
| `$env:GITHUB_WORKSPACE` to find CI scripts | Use hardcoded `N:\Code\Workspace\Local-CI-CD-System\scripts\` |
| `actions/checkout@v4` in build jobs | Omit it; source is handled by Invoke-CIJob.ps1 |
| `runs-on: ubuntu-latest` or `windows-latest` | Use `windows-build` or `linux-build` — cloud runners are not available |
| `&&` in PowerShell run blocks | Not valid in PS 5.1; use `if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }` |
| Hardcoded IP in `-VMIPAddress` | Omit it; auto-detected via `vmrun getGuestIPAddress` |
| `-TemplatePath` for Linux without `GITEA_CI_LINUX_TEMPLATE_PATH` | Pass `$env:GITEA_CI_LINUX_TEMPLATE_PATH` or the full path explicitly |
| Forgetting `-SnapshotName 'BaseClean-Linux'` for Linux | Linux template uses a different snapshot name than Windows (`BaseClean`) |
| Same `-JobId` for matrix jobs | Append matrix key: `${{ github.run_id }}-${{ matrix.config }}` |
| Mistake | Correct approach |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `shell: pwsh` | Use `shell: powershell` (PS 5.1, not Core) |
| SSH alias URL with `-UseGitClone` | Use `https://gitea.emulab.it/...` for UseGitClone; SSH alias is host-only |
| HTTPS URL without `-UseGitClone` | SSH alias `ssh://gitea-ci/...` for host-clone mode |
| `$env:GITHUB_WORKSPACE` to find CI scripts | Use hardcoded `N:\Code\Workspace\Local-CI-CD-System\scripts\` |
| `actions/checkout@v4` in build jobs | Omit it; source is handled by Invoke-CIJob.ps1 |
| `runs-on: ubuntu-latest` or `windows-latest` | Use `windows-build` or `linux-build` — cloud runners are not available |
| `&&` in PowerShell run blocks | Not valid in PS 5.1; use `if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }` |
| Hardcoded IP in `-VMIPAddress` | Omit it; auto-detected via `vmrun getGuestIPAddress` |
| `-TemplatePath` for Linux without `GITEA_CI_LINUX_TEMPLATE_PATH` | Pass `$env:GITEA_CI_LINUX_TEMPLATE_PATH` or the full path explicitly |
| Forgetting `-SnapshotName 'BaseClean-Linux'` for Linux | Linux template uses a different snapshot name than Windows (`BaseClean`) |
| Same `-JobId` for matrix jobs | Append matrix key: `${{ github.run_id }}-${{ matrix.config }}` |