stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

feat(devops): local GitLab secret bootstrap + integration registration scripts

Browse Source 
Adds PowerShell helpers to seed the local Stella Ops stack with a working
GitLab + integrations configuration:
- bootstrap-local-gitlab-secrets.ps1 provisions GitLab's JWT signing secret
  and admin PAT into Vault/Authority.
- register-local-integrations.ps1 POSTs the canonical integration records
  (GitLab, Jenkins, Harbor, Gitea, Nexus, etc.) against the Integrations
  service for first-run local environments.

Docs: INSTALL_GUIDE.md + integrations/LOCAL_SERVICES.md document the new
helpers. devops/compose README and router-gateway-local.json get the
corresponding route wiring. Two new sprint files track the follow-on work
(SPRINT_20260413_002, SPRINT_20260413_003).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
master
2026-04-13 21:59:13 +03:00
parent 71dd1efc34
commit a19987979d
8 changed files with 934 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/INSTALL_GUIDE.md
View File

@@ -171,6 +171,50 @@ docker compose -f docker-compose.stella-ops.yml ps
curl -k https://stella-ops.local # should return the Angular UI
```
For a fresh local developer install, populate the live integration catalog with:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/register-local-integrations.ps1 `
-Tenant demo-prod
```
This converges the default local-ready lane to 13 healthy providers:
Harbor fixture, Docker Registry, Nexus, GitHub App fixture, Gitea, Jenkins,
Vault, Consul, eBPF runtime-host fixture, MinIO, and the three feed mirror
providers (`StellaOpsMirror`, `NvdMirror`, `OsvMirror`).
GitLab server/CI and the GitLab registry remain opt-in because they require
Vault-backed credentials. The scripted local path is:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/bootstrap-local-gitlab-secrets.ps1 `
-VerifyRegistry
powershell -ExecutionPolicy Bypass -File scripts/register-local-integrations.ps1 `
-Tenant demo-prod `
-IncludeGitLab
powershell -ExecutionPolicy Bypass -File scripts/register-local-integrations.ps1 `
-Tenant demo-prod `
-IncludeGitLab `
-IncludeGitLabRegistry
```
Or run the GitLab-backed registration in one step:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/register-local-integrations.ps1 `
-Tenant demo-prod `
-IncludeGitLab `
-IncludeGitLabRegistry `
-BootstrapGitLabSecrets
```
`scripts/bootstrap-local-gitlab-secrets.ps1` reuses a valid `secret/gitlab`
secret when possible and otherwise rotates the local `stella-local-integration`
PAT, then writes both `authref://vault/gitlab#access-token` and
`authref://vault/gitlab#registry-basic` into the dev Vault.
## Air-gapped deployments
For offline/air-gapped environments, use the sealed CI compose file and offline telemetry overlay:

67
docs/implplan/SPRINT_20260413_002_Integrations_gitlab_secret_bootstrap_automation.md Normal file
View File

@@ -0,0 +1,67 @@
# Sprint 20260413-002 - GitLab Secret Bootstrap Automation
## Topic & Scope
- Remove the last manual local GitLab secret-seeding step from the local integrations lane by scripting PAT rotation and Vault writeback.
- Keep GitLab local integrations opt-in, but make the credential bootstrap reusable and idempotent from repo-owned scripts.
- Sync the setup docs with the automated GitLab path and verify the one-command registration flow on this machine.
- Working directory: `scripts/`.
- Expected evidence: script runs, Vault secret metadata, GitLab PAT inventory, integration registration output, and updated setup docs.
## Dependencies & Concurrency
- Depends on the archived local scratch-setup sprint `docs-archived/implplan/SPRINT_20260413_001_Platform_scratch_setup_local_integrations.md`.
- Safe parallelism is low because the bootstrap rotates live local GitLab PAT material and updates a shared Vault path.
- Cross-directory edits are allowed for `scripts/**`, `docs/**`, and `devops/**` only.
## Documentation Prerequisites
- `docs/INSTALL_GUIDE.md`
- `docs/integrations/LOCAL_SERVICES.md`
- `devops/compose/README.md`
- `docs-archived/implplan/SPRINT_20260413_001_Platform_scratch_setup_local_integrations.md`
## Delivery Tracker
### GITLAB-001 - Automate local GitLab PAT bootstrap into Vault
Status: DONE
Dependency: none
Owners: Developer / Ops Integrator
Task description:
- Add a repo-owned script that can bootstrap or rotate the local GitLab personal access token used by the GitLab SCM, CI, and registry integrations.
- The script must reuse the existing `secret/gitlab` material when it still verifies, rotate stale tokens deterministically, and write the resulting auth material back into the dev Vault without requiring manual UI work.
Completion criteria:
- [x] A local script can create or rotate the GitLab PAT and write `access-token` plus `registry-basic` into `secret/gitlab`.
- [x] The script reuses a valid local secret instead of rotating on every run.
- [x] The script verifies the GitLab API token and optional registry token exchange before reporting success.
### GITLAB-002 - Wire and verify the automated GitLab registration path
Status: DONE
Dependency: GITLAB-001
Owners: Developer / Documentation Author
Task description:
- Wire the local integration helper so GitLab-backed registration can invoke the bootstrap automatically when requested.
- Update the setup docs to make the automated GitLab path the documented local default, keeping manual Vault writes only as an override path.
Completion criteria:
- [x] `scripts/register-local-integrations.ps1` can invoke the GitLab bootstrap automatically.
- [x] The install and local-service docs describe the automated GitLab path and the one-command registration flow.
- [x] The GitLab-backed integration registration path is rerun successfully on this machine with the automated bootstrap enabled.
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-04-13 | Sprint created to automate the remaining local GitLab PAT and Vault bootstrap step after the archived local scratch-setup sprint closed green. | Developer |
| 2026-04-13 | Confirmed the local GitLab CE admin OAuth password-grant, PAT list, PAT create, and PAT revoke APIs all work against the running local heavy GitLab profile. | Developer |
| 2026-04-13 | Added `scripts/bootstrap-local-gitlab-secrets.ps1` to reuse or rotate the local `stella-local-integration` PAT, verify API plus registry token exchange, and write `secret/gitlab` metadata into the dev Vault. | Developer |
| 2026-04-13 | Updated `scripts/register-local-integrations.ps1` with `-BootstrapGitLabSecrets`, then re-ran `powershell -ExecutionPolicy Bypass -File scripts/register-local-integrations.ps1 -Tenant demo-prod -IncludeGitLab -IncludeGitLabRegistry -BootstrapGitLabSecrets`; result: all 16 local integrations converged `Healthy`. | Developer |
| 2026-04-13 | Updated `docs/INSTALL_GUIDE.md`, `docs/integrations/LOCAL_SERVICES.md`, and `devops/compose/README.md` to make the scripted GitLab bootstrap the documented local path and keep manual Vault writes as the override path. | Developer |
## Decisions & Risks
- Decision: the local GitLab bootstrap continues to use the deterministic local root account (`root` / `Stella2026!`) because that credential is already the documented dev default in `docker-compose.integrations.yml`.
- Decision: the bootstrap PAT name is fixed to `stella-local-integration`; reruns revoke earlier active PATs with the same name before creating a replacement token so the local token inventory does not grow without bound.
- Decision: the script stores `bootstrap-user`, `token-name`, `expires-at`, and `rotated-at` alongside `access-token` and `registry-basic` in `secret/gitlab` so local operators can inspect the current bootstrap state without exposing extra secret sources.
- Risk: there is no existing PowerShell unit-test harness in this repo for local ops scripts, so verification for this change is live-script execution against the local GitLab and Vault containers plus the integration registration pass.
- Risk: the GitLab local integrations remain opt-in because the heavy GitLab profile and optional registry surface still carry materially higher resource cost than the default local provider lane.
## Next Checkpoints
- If the local GitLab root password is changed in compose, update `scripts/bootstrap-local-gitlab-secrets.ps1` defaults and the associated docs in the same change.
- If the local GitLab topology moves away from the root account, replace the bootstrap user model with a dedicated seeded local service user and update the Vault metadata schema accordingly.

78
docs/implplan/SPRINT_20260413_003_Web_ui_driven_local_setup_rerun.md Normal file
View File

@@ -0,0 +1,78 @@
# Sprint 20260413-003 -- UI Driven Local Setup Rerun
## Topic & Scope
- Re-run the Stella Ops local setup from zero Stella runtime state and use the browser UI as the operator surface instead of the CLI registration path.
- Verify which parts of the setup wizard and integrations hub are truly live and which parts still depend on script/API-only bootstrap behind the scenes.
- Leave behind truthful evidence: what the UI can complete today, what was completed via UI, and any remaining product gaps that still prevent a full UI-only bootstrap.
- Working directory: `.`.
- Expected evidence: sprint log, live browser verification, container health, and final integration health results.
## Dependencies & Concurrency
- Required docs: `docs/modules/platform/architecture-overview.md`, `docs/INSTALL_GUIDE.md`, `docs/integrations/LOCAL_SERVICES.md`, `src/Web/StellaOps.Web/AGENTS.md`.
- Builds on the local-stack convergence work in [SPRINT_20260409_002_Platform_local_stack_regression_retest.md](/C:/dev/New%20folder/git.stella-ops.org/docs/implplan/SPRINT_20260409_002_Platform_local_stack_regression_retest.md) and the local-integration automation in [SPRINT_20260413_002_Integrations_gitlab_secret_bootstrap_automation.md](/C:/dev/New%20folder/git.stella-ops.org/docs/implplan/SPRINT_20260413_002_Integrations_gitlab_secret_bootstrap_automation.md).
- Safe parallelism: none during wipe/setup because the environment reset is global to the machine. Browser verification can run only after the platform is reachable.
## Documentation Prerequisites
- `docs/modules/platform/architecture-overview.md`
- `docs/INSTALL_GUIDE.md`
- `docs/integrations/LOCAL_SERVICES.md`
- `src/Web/StellaOps.Web/AGENTS.md`
## Delivery Tracker
### UISETUP-001 - Reset the local Stella runtime to zero state
Status: DOING
Dependency: none
Owners: Developer / QA
Task description:
- Remove Stella-owned runtime containers, volumes, networks, and local images so the rerun starts from zero Stella platform state rather than from the already converged environment.
- Re-run the documented setup entrypoint needed to bring the platform back to a reachable browser state.
Completion criteria:
- [ ] Stella-owned containers, volumes, and networks are removed before the rerun.
- [ ] The documented local setup entrypoint is executed successfully after the wipe.
- [ ] `https://stella-ops.local` becomes reachable again for browser-driven setup.
### UISETUP-002 - Drive the operator setup through the browser UI
Status: TODO
Dependency: UISETUP-001
Owners: Developer / QA
Task description:
- Use the live browser UI to sign in, complete the setup wizard flow, and exercise the integrations onboarding surfaces instead of provisioning through the CLI registration helper.
- Record which configuration steps are truly persisted/provisioned by the UI versus which ones are session-only or still backend-limited.
Completion criteria:
- [ ] The setup wizard is exercised through the live browser against the rebuilt stack.
- [ ] The integrations UI is used for the available local integration onboarding flows.
- [ ] Any step that is not truly UI-provisioned is captured explicitly with supporting evidence.
### UISETUP-003 - Close documentation and evidence gaps for the UI path
Status: TODO
Dependency: UISETUP-002
Owners: Developer / Documentation
Task description:
- Update operator-facing docs if the actual UI-driven setup path differs from the current documented local bootstrap.
- Record the final verified state, remaining non-UI gaps, and any follow-up implementation needs in the sprint log and linked docs.
Completion criteria:
- [ ] Docs reflect the verified UI-driven setup reality.
- [ ] Final health and integration results are logged in the execution log.
- [ ] Remaining non-UI blockers are called out explicitly rather than glossed over.
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-04-13 | Sprint created for a zero-state local rerun that must use the live browser UI for setup and integration onboarding wherever the product currently supports it. | Developer |
| 2026-04-13 | Removed all `stellaops-*` containers, `compose_*` / `stellaops_*` volumes, the `stellaops` / `stellaops_frontdoor` networks, and all `stellaops/*:dev` images to return the machine to zero Stella runtime state before the rerun. | Developer |
| 2026-04-13 | Started the documented machine-level bootstrap with `scripts/setup.ps1 -QaIntegrationFixtures`; this restores the platform and fixture-backed frontdoor but not the full real-provider integrations compose lane. | Developer |
| 2026-04-13 | Code inspection ahead of the live browser run found two likely UI-path gaps to validate: the setup wizard backend persists much of its state only in-session, and the integrations onboarding wizard currently requires a non-empty `AuthRef URI` even though the backend API itself accepts null auth refs for local no-auth connectors. | Developer |
## Decisions & Risks
- Decision: this rerun uses the real browser UI as the operator surface and treats CLI/bootstrap helpers only as fallback evidence if the product lacks a true UI path.
- Risk: the setup wizard backend may still persist parts of the flow only in-memory/session scope, which would make a strict UI-only bootstrap impossible without follow-on implementation work.
- Risk: some local integrations may still require credentials to exist before the UI can complete onboarding, especially GitLab and Vault-backed secrets.
## Next Checkpoints
- Complete the zero-state wipe and restore the platform to a reachable browser state.
- Drive the setup wizard and integrations flows through the UI.
- Record the exact boundary between UI-complete setup and script/API-only gaps.

57
docs/integrations/LOCAL_SERVICES.md
View File

@@ -86,6 +86,59 @@ docker compose -f docker-compose.integrations.yml ps
docker compose -f docker-compose.integrations.yml ps gitea
```
### 4. Register the local integration catalog
After the core stack plus the local provider lanes are running, register the
catalog entries that Stella Ops can exercise immediately from a fresh local
install:
```powershell
powershell -ExecutionPolicy Bypass -File scripts/register-local-integrations.ps1 `
-Tenant demo-prod
```
This converges the default local-ready lane to 13 healthy entries:
- Harbor fixture
- Docker Registry
- Nexus
- GitHub App fixture
- Gitea
- Jenkins
- Vault
- Consul
- eBPF runtime-host fixture
- MinIO (`S3Compatible`)
- StellaOps mirror
- NVD mirror
- OSV mirror
Optional GitLab providers require Vault-backed credentials. The recommended
local flow is:
```powershell
# Reuse or rotate the local GitLab bootstrap PAT and write it to Vault.
powershell -ExecutionPolicy Bypass -File scripts/bootstrap-local-gitlab-secrets.ps1 `
-VerifyRegistry
# Register SCM + CI using the bootstrapped authref://vault/gitlab#access-token
powershell -ExecutionPolicy Bypass -File scripts/register-local-integrations.ps1 `
-Tenant demo-prod `
-IncludeGitLab
# Also requires GitLab registry enabled; uses authref://vault/gitlab#registry-basic
powershell -ExecutionPolicy Bypass -File scripts/register-local-integrations.ps1 `
-Tenant demo-prod `
-IncludeGitLab `
-IncludeGitLabRegistry
# Or do the GitLab-backed registration in one step
powershell -ExecutionPolicy Bypass -File scripts/register-local-integrations.ps1 `
-Tenant demo-prod `
-IncludeGitLab `
-IncludeGitLabRegistry `
-BootstrapGitLabSecrets
```
`docker-compose.testing.yml` is the separate infrastructure-test lane. It starts `postgres-test`, `valkey-test`, mocks, and an isolated Gitea profile on different ports; it does not start Consul or GitLab.
---
@@ -206,7 +259,7 @@ vault kv put secret/jenkins api-token="your-jenkins-token"
# Store Nexus admin password
vault kv put secret/nexus admin-password="your-nexus-password"
# Store GitLab PATs for API and registry access
# Store GitLab PATs for API and registry access (manual override path)
vault kv put secret/gitlab access-token="glpat-your-token" registry-basic="root:glpat-your-token"
```
@@ -326,12 +379,14 @@ GITLAB_ENABLE_REGISTRY=true GITLAB_ENABLE_PACKAGES=true \
**Stella Ops integration config (SCM / CI):**
- Endpoint: `http://gitlab.stella-ops.local:8929`
- AuthRef: `authref://vault/gitlab#access-token`
- Bootstrap helper: `powershell -ExecutionPolicy Bypass -File scripts/bootstrap-local-gitlab-secrets.ps1`
**Stella Ops integration config (Registry):**
- Endpoint: `http://gitlab.stella-ops.local:5050`
- AuthRef: `authref://vault/gitlab#registry-basic`
- Secret format: `username:personal-access-token` (local default: `root:<token>`)
- The Docker registry connector follows GitLab's `WWW-Authenticate: Bearer` challenge and exchanges this basic secret against `/jwt/auth` before retrying catalog and tag probes.
- `scripts/bootstrap-local-gitlab-secrets.ps1 -VerifyRegistry` reuses a valid local Vault secret when possible and otherwise rotates the local `stella-local-integration` PAT before writing both authrefs.
---