docs: align documentation with session fixes
Reconcile docs with the end-to-end pipeline fixes: - upload/download-artifact @v4 -> @v3 (Gitea GHES) in WORKFLOW-AUTHORING and workflow-example.yml; add Common Mistakes rows (v4, action ref form + DEFAULT_ACTIONS_URL, public action repo). - BEST-PRACTICES / README / HOST-SETUP: guest credential must live in the LocalSystem vault with a host-qualified username; document Set-CIGuestCredential.ps1 / Test-CIGuestWinRM.ps1 and auth=ntlm. - README / AGENTS / HOST-SETUP: production venv install is NON-editable (LocalSystem); no CI workflow may install into it. - HOST-SETUP: add DEFAULT_ACTIONS_URL=github + full-URL uses: + public repo + @main requirements discovered during validation. - Correct stale repo name local-ci-system -> local-ci-cd-system. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Simone
+27
-16
@@ -4,29 +4,40 @@
|
||||
|
||||
### Do NOT store credentials in scripts or config files
|
||||
|
||||
The scripts use `-GuestCredentialTarget` (a Windows Credential Manager target name)
|
||||
rather than plaintext username/password parameters. Store credentials once:
|
||||
The guest VM credential is referenced by target name (`BuildVMGuest`,
|
||||
`GITEA_CI_GUEST_CRED_TARGET`) and read by the Python orchestrator via the
|
||||
`keyring` library — never as plaintext parameters.
|
||||
|
||||
> **Critical: store it in the LocalSystem vault, not your user vault.**
|
||||
> act_runner runs as the `LocalSystem` service account. Windows Credential
|
||||
> Manager / keyring vaults are **per-user**. A credential added with
|
||||
> `cmdkey` or the Credential Manager UI from an interactive admin session
|
||||
> lands in *your* vault and is invisible to the runner, which then fails
|
||||
> with `Credential 'BuildVMGuest' not found in keyring`.
|
||||
|
||||
> **Username must be host-qualified.** The guest is a workgroup machine;
|
||||
> NTLM rejects a bare `ci_build` with `SEC_E_UNKNOWN_CREDENTIALS`. Store
|
||||
> it as `WINBUILD-2025\ci_build` (the guest computer name, i.e. the WinRM
|
||||
> TLS certificate CN). The WinRM transport forces `auth='ntlm'` for the
|
||||
> same reason (Negotiate→Kerberos is meaningless without a domain).
|
||||
|
||||
Store (or rotate) the credential with the helper, which writes into the
|
||||
SYSTEM vault via the production venv's `keyring` (run elevated):
|
||||
|
||||
```powershell
|
||||
# Run on host (once, before first CI job)
|
||||
cmdkey /generic:BuildVMGuest /user:MACHINENAME\ci_build /pass:YourStrongPassword
|
||||
.\scripts\Set-CIGuestCredential.ps1 -UserName 'WINBUILD-2025\ci_build'
|
||||
```
|
||||
|
||||
Retrieve in scripts via the `CredentialManager` PowerShell module:
|
||||
|
||||
```powershell
|
||||
Install-Module CredentialManager -Scope CurrentUser
|
||||
$cred = Get-StoredCredential -Target 'BuildVMGuest'
|
||||
```
|
||||
It prompts for the password securely, writes it to the SYSTEM vault, and
|
||||
verifies the read-back as SYSTEM. Diagnose WinRM reachability/auth with
|
||||
`.\scripts\Test-CIGuestWinRM.ps1 -IpAddress <guest-ip>`.
|
||||
|
||||
### Rotate credentials quarterly
|
||||
|
||||
1. Update password in the template VM (requires rebuilding `BaseClean` snapshot)
|
||||
2. Update Windows Credential Manager on the host:
|
||||
```
|
||||
cmdkey /generic:BuildVMGuest /user:MACHINENAME\ci_build /pass:NewPassword
|
||||
```
|
||||
3. No script changes required — they reference the target name, not the password.
|
||||
1. Update the password in the template VM (rebuild the `BaseClean` snapshot).
|
||||
2. Re-run `Set-CIGuestCredential.ps1 -UserName 'WINBUILD-2025\ci_build'`
|
||||
with the new password.
|
||||
3. No code changes required — the orchestrator references the target name.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -91,6 +91,32 @@ Apri PowerShell **come Administrator**, poi:
|
||||
- Avvia servizio (`SERVICE_AUTO_START`)
|
||||
7. **Configura SSH alias `gitea-ci`** in `~/.ssh/config` (HostName, Port, User git)
|
||||
|
||||
### Note operative (scoperte in validazione end-to-end)
|
||||
|
||||
Setup-Host.ps1 da solo **non basta** per la pipeline Python su runner
|
||||
LocalSystem. Dopo Setup-Host:
|
||||
|
||||
- **Credenziale guest nel vault SYSTEM, username host-qualificato.** Lo
|
||||
step 4 scrive in Windows Credential Manager dell'utente interattivo →
|
||||
invisibile ad act_runner (LocalSystem). Esegui (elevato):
|
||||
`\.\scripts\Set-CIGuestCredential.ps1 -UserName 'WINBUILD-2025\ci_build'`.
|
||||
Bare `ci_build` viene rifiutato da NTLM (`SEC_E_UNKNOWN_CREDENTIALS`):
|
||||
usa il computer name del guest (= CN del cert WinRM). Diagnostica:
|
||||
`\.\scripts\Test-CIGuestWinRM.ps1 -IpAddress <guest-ip>`.
|
||||
- **venv di produzione = install non-editable.** Popola
|
||||
`F:\CI\python\venv` con `python -m pip install .` dal repo reale —
|
||||
**mai** `pip install -e .` (il `.pth` punta a un path che LocalSystem
|
||||
non risolve → `No module named ci_orchestrator`). Vedi
|
||||
`plans/PhaseA-user-checklist.md` Passo 1. Nessun workflow CI deve
|
||||
installare in quel venv (lint usa un venv effimero per-job).
|
||||
- **Gitea `app.ini`:** imposta `[actions] DEFAULT_ACTIONS_URL = github`
|
||||
e referenzia l'action col **URL completo**
|
||||
(`https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main`)
|
||||
così le action GitHub (checkout, upload-artifact) restano risolvibili
|
||||
e l'action locale punta all'istanza. Il repo `local-ci-cd-system` deve
|
||||
essere **pubblico** (il runner clona l'action senza autenticazione) e
|
||||
l'action deve esistere su `@main` (il ref che il runner clona).
|
||||
|
||||
---
|
||||
|
||||
## Parametri principali
|
||||
|
||||
@@ -254,7 +254,7 @@ jobs:
|
||||
|
||||
- name: Upload artifacts
|
||||
if: success()
|
||||
uses: actions/upload-artifact@v4
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: build-${{ github.ref_name }}
|
||||
path: F:\CI\Artifacts\${{ github.run_id }}\artifacts.zip
|
||||
@@ -262,7 +262,7 @@ jobs:
|
||||
|
||||
- name: Upload logs on failure
|
||||
if: failure()
|
||||
uses: actions/upload-artifact@v4
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: build-logs-${{ github.run_id }}
|
||||
path: F:\CI\Artifacts\${{ github.run_id }}\*.log
|
||||
@@ -308,7 +308,7 @@ jobs:
|
||||
|
||||
- name: Upload artifacts
|
||||
if: success()
|
||||
uses: actions/upload-artifact@v4
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: build-linux-${{ github.ref_name }}
|
||||
path: F:\CI\Artifacts\${{ github.run_id }}\artifacts.zip
|
||||
@@ -359,7 +359,7 @@ jobs:
|
||||
|
||||
- name: Upload artifacts
|
||||
if: success()
|
||||
uses: actions/upload-artifact@v4
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: build-${{ github.ref_name }}
|
||||
path: F:\CI\Artifacts\${{ github.run_id }}\artifacts.zip
|
||||
@@ -404,7 +404,7 @@ jobs:
|
||||
|
||||
- name: Upload artifacts
|
||||
if: success()
|
||||
uses: actions/upload-artifact@v4
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: build-linux-${{ github.ref_name }}
|
||||
path: F:\CI\Artifacts\${{ github.run_id }}\artifacts.zip
|
||||
@@ -502,7 +502,7 @@ jobs:
|
||||
|
||||
- name: Upload artifacts
|
||||
if: success()
|
||||
uses: actions/upload-artifact@v4
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: build-${{ matrix.config }}-${{ github.ref_name }}
|
||||
path: F:\CI\Artifacts\${{ github.run_id }}-${{ matrix.config }}\artifacts.zip
|
||||
@@ -573,3 +573,6 @@ the cleanup task `Cleanup-OrphanedBuildVMs.ps1` handles these cases.
|
||||
| `-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 }}` |
|
||||
| `actions/upload-artifact@v4` / `download-artifact@v4` | Use `@v3`. Gitea reports as GHES; @v4 (`@actions/artifact` v2 / Twirp API) fails with `GHESNotSupportedError`. |
|
||||
| Short action ref `Simone/local-ci-cd-system/...@main` | Use the full URL `https://gitea.emulab.it/Simone/local-ci-cd-system/.gitea/actions/local-ci-build@main`; with `[actions] DEFAULT_ACTIONS_URL = github` in Gitea's app.ini this keeps GitHub actions (checkout, upload-artifact) resolvable while pointing the composite action at the local instance. The action repo must be on `@main` (the ref the runner clones). |
|
||||
| Composite action referenced from a private/internal repo | The runner clones the action repo unauthenticated. Make `local-ci-cd-system` public, or the clone fails with `authentication required: Unauthorized`. |
|
||||
|
||||
Reference in New Issue
Block a user