# StellaOps CI/CD Infrastructure

Comprehensive CI/CD infrastructure for the StellaOps platform using Gitea Actions.

## Quick Reference

| Resource | Location |
|----------|----------|
| Workflows | `.gitea/workflows/` (96 workflows) |
| Scripts | `.gitea/scripts/` |
| Documentation | `.gitea/docs/` |
| DevOps Configs | `devops/` |
| Release Manifests | `devops/releases/` |

## Workflow Categories

### Core Build & Test

| Workflow | File | Description |
|----------|------|-------------|
| Build Test Deploy | `build-test-deploy.yml` | Main CI pipeline for all modules |
| Test Matrix | `test-matrix.yml` | Unified test execution with TRX reporting |
| Test Lanes | `test-lanes.yml` | Parallel test lane execution |
| Integration Tests | `integration-tests-gate.yml` | Integration test quality gate |

### Release Pipelines

| Workflow | File | Description |
|----------|------|-------------|
| Suite Release | `release-suite.yml` | Full platform release (YYYY.MM versioning) |
| Service Release | `service-release.yml` | Per-service release pipeline |
| Module Publish | `module-publish.yml` | NuGet and container publishing |
| Release Validation | `release-validation.yml` | Post-release verification |
| Promote | `promote.yml` | Environment promotion (dev/stage/prod) |

### CLI & SDK

| Workflow | File | Description |
|----------|------|-------------|
| CLI Build | `cli-build.yml` | Multi-platform CLI builds |
| CLI Chaos Parity | `cli-chaos-parity.yml` | CLI behavioral consistency tests |
| SDK Generator | `sdk-generator.yml` | Client SDK generation |
| SDK Publish | `sdk-publish.yml` | SDK package publishing |

### Security & Compliance

| Workflow | File | Description |
|----------|------|-------------|
| Artifact Signing | `artifact-signing.yml` | Cosign artifact signing |
| Dependency Security | `dependency-security-scan.yml` | Vulnerability scanning |
| License Audit | `license-audit.yml` | OSS license compliance |
| License Gate | `dependency-license-gate.yml` | PR license compliance gate |
| Crypto Compliance | `crypto-compliance.yml` | Cryptographic compliance checks |
| Provenance Check | `provenance-check.yml` | Supply chain provenance |

### Attestation & Evidence

| Workflow | File | Description |
|----------|------|-------------|
| Attestation Bundle | `attestation-bundle.yml` | in-toto attestation bundling |
| Evidence Locker | `evidence-locker.yml` | Evidence artifact storage |
| VEX Proof Bundles | `vex-proof-bundles.yml` | VEX proof generation |
| Signals Evidence | `signals-evidence-locker.yml` | Signal evidence collection |
| Signals DSSE Sign | `signals-dsse-sign.yml` | DSSE envelope signing |

### Scanner & Analysis

| Workflow | File | Description |
|----------|------|-------------|
| Scanner Analyzers | `scanner-analyzers.yml` | Language analyzer CI |
| Scanner Determinism | `scanner-determinism.yml` | Output reproducibility tests |
| Reachability Bench | `reachability-bench.yaml` | Reachability analysis benchmarks |
| Reachability Corpus | `reachability-corpus-ci.yml` | Corpus maintenance |
| EPSS Ingest Perf | `epss-ingest-perf.yml` | EPSS ingestion performance |

### Determinism & Reproducibility

| Workflow | File | Description |
|----------|------|-------------|
| Determinism Gate | `determinism-gate.yml` | Build determinism quality gate |
| Cross-Platform Det. | `cross-platform-determinism.yml` | Cross-OS reproducibility |
| Bench Determinism | `bench-determinism.yml` | Benchmark determinism |
| E2E Reproducibility | `e2e-reproducibility.yml` | End-to-end reproducibility |

### Module-Specific

| Workflow | File | Description |
|----------|------|-------------|
| Advisory AI Release | `advisory-ai-release.yml` | AI module release |
| AOC Guard | `aoc-guard.yml` | AOC policy enforcement |
| Authority Key Rotation | `authority-key-rotation.yml` | Key rotation automation |
| Concelier Tests | `concelier-attestation-tests.yml` | Concelier attestation tests |
| Findings Ledger | `findings-ledger-ci.yml` | Findings ledger CI |
| Policy Lint | `policy-lint.yml` | Policy DSL validation |
| Router Chaos | `router-chaos.yml` | Router chaos testing |
| Signals CI | `signals-ci.yml` | Signals module CI |

### Infrastructure & Ops

| Workflow | File | Description |
|----------|------|-------------|
| Containers Multiarch | `containers-multiarch.yml` | Multi-architecture builds |
| Docker Regional | `docker-regional-builds.yml` | Regional Docker builds |
| Helm Validation | (via scripts) | Helm chart validation |
| Console Runner | `console-runner-image.yml` | Runner image builds |
| Obs SLO | `obs-slo.yml` | Observability SLO checks |
| Obs Stream | `obs-stream.yml` | Telemetry streaming |

### Documentation & API

| Workflow | File | Description |
|----------|------|-------------|
| Docs | `docs.yml` | Documentation site build |
| OAS CI | `oas-ci.yml` | OpenAPI spec validation |
| API Governance | `api-governance.yml` | API governance checks |
| Schema Validation | `schema-validation.yml` | JSON schema validation |

### Dependency Management

| Workflow | File | Description |
|----------|------|-------------|
| Renovate | `renovate.yml` | Automated dependency updates |
| License Gate | `dependency-license-gate.yml` | License compliance gate |
| Security Scan | `dependency-security-scan.yml` | Vulnerability scanning |

## Script Categories

### Build Scripts (`scripts/build/`)

| Script | Purpose |
|--------|---------|
| `build-cli.sh` | Build CLI for specific runtime |
| `build-multiarch.sh` | Multi-architecture container builds |
| `build-airgap-bundle.sh` | Air-gap deployment bundle |

### Test Scripts (`scripts/test/`)

| Script | Purpose |
|--------|---------|
| `determinism-run.sh` | Determinism verification |
| `run-fixtures-check.sh` | Test fixture validation |

### Validation Scripts (`scripts/validate/`)

| Script | Purpose |
|--------|---------|
| `validate-compose.sh` | Docker Compose validation |
| `validate-helm.sh` | Helm chart validation |
| `validate-licenses.sh` | License compliance |
| `validate-migrations.sh` | Database migration validation |
| `validate-sbom.sh` | SBOM validation |
| `validate-spdx.sh` | SPDX format validation |
| `validate-vex.sh` | VEX document validation |
| `validate-workflows.sh` | Workflow YAML validation |
| `verify-binaries.sh` | Binary integrity verification |

### Signing Scripts (`scripts/sign/`)

| Script | Purpose |
|--------|---------|
| `sign-authority-gaps.sh` | Sign authority gap attestations |
| `sign-policy.sh` | Sign policy artifacts |
| `sign-signals.sh` | Sign signals data |

### Release Scripts (`scripts/release/`)

| Script | Purpose |
|--------|---------|
| `build_release.py` | Suite release orchestration |
| `verify_release.py` | Release verification |
| `bump-service-version.py` | Service version management |
| `read-service-version.sh` | Read current version |
| `generate-docker-tag.sh` | Generate Docker tags |
| `generate_changelog.py` | AI-assisted changelog |
| `generate_suite_docs.py` | Release documentation |
| `generate_compose.py` | Docker Compose generation |
| `collect_versions.py` | Version collection |
| `check_cli_parity.py` | CLI version parity |

### Evidence Scripts (`scripts/evidence/`)

| Script | Purpose |
|--------|---------|
| `upload-all-evidence.sh` | Upload all evidence bundles |
| `signals-upload-evidence.sh` | Upload signals evidence |
| `zastava-upload-evidence.sh` | Upload Zastava evidence |

### Metrics Scripts (`scripts/metrics/`)

| Script | Purpose |
|--------|---------|
| `compute-reachability-metrics.sh` | Reachability analysis metrics |
| `compute-ttfs-metrics.sh` | Time-to-first-scan metrics |
| `enforce-performance-slos.sh` | SLO enforcement |

### Utility Scripts (`scripts/util/`)

| Script | Purpose |
|--------|---------|
| `cleanup-runner-space.sh` | Runner disk cleanup |
| `dotnet-filter.sh` | .NET project filtering |
| `enable-openssl11-shim.sh` | OpenSSL 1.1 compatibility |

## Environment Variables

### Required Secrets

| Secret | Purpose | Workflows |
|--------|---------|-----------|
| `GITEA_TOKEN` | API access, commits | All |
| `RENOVATE_TOKEN` | Dependency bot access | `renovate.yml` |
| `COSIGN_PRIVATE_KEY_B64` | Artifact signing | Release pipelines |
| `AI_API_KEY` | Changelog generation | `release-suite.yml` |
| `REGISTRY_USERNAME` | Container registry | Build/deploy |
| `REGISTRY_PASSWORD` | Container registry | Build/deploy |
| `SSH_PRIVATE_KEY` | Deployment access | Deploy pipelines |

### Common Variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `DOTNET_VERSION` | `10.0.100` | .NET SDK version |
| `NODE_VERSION` | `20` | Node.js version |
| `RENOVATE_VERSION` | `37.100.0` | Renovate version |
| `REGISTRY_HOST` | `git.stella-ops.org` | Container registry |

## Versioning Strategy

### Suite Releases (Platform)

- Format: `YYYY.MM` with codenames (Ubuntu-style)
- Example: `2026.04 Nova`
- Triggered by: Tag `suite-YYYY.MM`
- Documentation: `docs/releases/YYYY.MM/`

### Service Releases (Individual)

- Format: SemVer `MAJOR.MINOR.PATCH`
- Docker tag: `{version}+{YYYYMMDDHHmmss}`
- Example: `1.2.3+20250128143022`
- Triggered by: Tag `service-{name}-v{version}`
- Version source: `src/Directory.Versions.props`

### Module Releases

- Format: SemVer `MAJOR.MINOR.PATCH`
- Triggered by: Tag `module-{name}-v{version}`

## Documentation

| Document | Description |
|----------|-------------|
| [Architecture](docs/architecture.md) | Workflow architecture and dependencies |
| [Scripts Inventory](docs/scripts.md) | Complete script documentation |
| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
| [Development Guide](docs/development.md) | Creating new workflows |
| [Runners](docs/runners.md) | Self-hosted runner setup |
| [Dependency Management](docs/dependency-management.md) | Renovate guide |

## Related Documentation

- [Main Architecture](../docs/07_HIGH_LEVEL_ARCHITECTURE.md)
- [DevOps README](../devops/README.md)
- [Release Versioning](../docs/releases/VERSIONING.md)
- [Offline Operations](../docs/24_OFFLINE_KIT.md)

## Contributing

1. Read `AGENTS.md` before making changes
2. Follow workflow naming conventions
3. Pin tool versions where possible
4. Keep workflows deterministic and offline-friendly
5. Update documentation when adding/modifying workflows
6. Test locally with `act` when possible

## Support

- Issues: https://git.stella-ops.org/stella-ops.org/issues
- Documentation: `docs/`