CI/CD Infrastructure Overview

This page is the entry point to the StellaOps CI/CD documentation. It explains how the pipeline is organized — the trigger tiers, workflow categories, environment promotion flow, and the determinism and supply-chain guarantees that the pipeline enforces. It is written for engineers who need to understand what runs when, and how to trigger releases.

Altitude note. Workflow names, schedules, and counts drift as the pipeline evolves; the authoritative definitions live in the workflow files under .gitea/workflows/. Treat the tables below as orientation and verify specifics against the workflow sources. Where this page cites a count or time, it is a snapshot, not a contract.

Quick links

• Workflow Triggers & Dependencies
• Release Pipelines
• Security Scanning
• Test Strategy
• CI Recipes
• CI Architecture
• Path Filters Reference

Architecture Overview

The StellaOps CI/CD infrastructure uses Gitea Actions (GitHub Actions compatible) with a sophisticated multi-tier triggering strategy designed for:

• Determinism & Reproducibility - Identical builds across runs
• Offline-First Operation - Air-gap compatible pipelines
• Supply Chain Security - SLSA Level 2-3 compliance
• Developer Velocity - Fast PR feedback with comprehensive nightly testing

Pipeline Tiers

┌─────────────────────────────────────────────────────────────────────────┐
│                        TRIGGER HIERARCHY                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  TIER 1: PR GATING (Every Pull Request)                                │
│  ├── test-matrix.yml (Unit, Architecture, Contract, Integration,       │
│  │                    Security, Golden)                                 │
│  ├── build-test-deploy.yml (Build verification)                        │
│  ├── policy-lint.yml (Policy file validation)                          │
│  ├── sast-scan.yml (Static security analysis)                          │
│  └── docs.yml (Documentation validation)                               │
│                                                                         │
│  TIER 2: MAIN BRANCH (Post-Merge)                                      │
│  ├── All Tier 1 workflows                                              │
│  ├── build-test-deploy.yml → Deploy stage (staging environment)        │
│  ├── integration-tests-gate.yml → Extended coverage                    │
│  └── coverage-report (Full coverage analysis)                          │
│                                                                         │
│  TIER 3: SCHEDULED (Nightly/Weekly)                                    │
│  ├── nightly-regression.yml (2:00 AM UTC daily)                        │
│  ├── test-matrix.yml → Extended tests (5:00 AM UTC daily)              │
│  ├── dependency-security-scan.yml (2:00 AM UTC Sunday)                 │
│  ├── renovate.yml (3:00 AM & 3:00 PM UTC daily)                        │
│  ├── sast-scan.yml (3:30 AM UTC Monday)                                │
│  └── migration-test.yml (4:30 AM UTC daily)                            │
│                                                                         │
│  TIER 4: RELEASE (Tag-Triggered)                                       │
│  ├── release-suite.yml (suite-YYYY.MM tags)                            │
│  ├── release.yml (v* tags)                                             │
│  └── module-publish.yml (module-*-v* tags)                             │
│                                                                         │
│  TIER 5: MANUAL (On-Demand)                                            │
│  ├── cli-build.yml, scanner-determinism.yml                            │
│  ├── rollback.yml, promote.yml                                         │
│  └── 20+ specialized test/debug workflows                              │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Workflow Categories

1. Core Build & Test (12 workflows)

2. Release Automation (8 workflows)

3. Security Scanning (6 workflows)

4. Quality Assurance (15 workflows)

5. Module-Specific (30+ workflows)

Specialized workflows for individual modules (Scanner, Concelier, Authority, etc.)

Trigger Quick Reference

Branch Patterns

Tag Patterns

Schedule Summary

Environment Flow

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│    PR    │───▶│  Staging │───▶│  Stable  │───▶│   LTS    │
│ (Preview)│    │  (Edge)  │    │ (Tested) │    │(Long-Term)│
└──────────┘    └──────────┘    └──────────┘    └──────────┘
     │               │               │               │
     │               │               │               │
     ▼               ▼               ▼               ▼
  PR tests      Auto-deploy      promote.yml    promote.yml
  (gating)      on main merge    (manual)       (manual)

Environment Matrix

Key Features

1. PR-Gating Tests

Required tests that must pass before merge:

• Unit Tests - Fast, isolated tests
• Architecture Tests - Dependency rule enforcement
• Contract Tests - API compatibility
• Integration Tests - PostgreSQL integration
• Security Tests - Security-focused assertions
• Golden Tests - Corpus-based validation

2. Determinism Verification

All builds produce identical outputs:

• Binary checksums compared across runs
• UTC timezone enforcement (TZ: UTC)
• Stable JSON serialization
• Reproducible SBOM generation

3. Supply Chain Security

• SBOM Generation - Syft for CycloneDX/SPDX
• Artifact Signing - Cosign/Sigstore integration
• Provenance - in-toto/DSSE attestations
• Dependency Scanning - Automated vulnerability detection

4. Rollback Automation

Emergency rollback via rollback.yml:

• Target: < 5 minute SLA
• Helm-based deployment rollback
• Health check verification
• Notification integration

Directory Structure

.gitea/
├── workflows/           # workflow definitions
│   ├── build-test-deploy.yml
│   ├── test-matrix.yml
│   ├── release-suite.yml
│   └── ...
├── scripts/             # CI/CD scripts
│   ├── build/           # Build orchestration
│   ├── test/            # Test execution
│   ├── release/         # Release automation
│   ├── sign/            # Signing operations
│   └── validate/        # Validation scripts
└── docs/                # CI-specific docs
    ├── architecture.md
    ├── scripts.md
    └── troubleshooting.md

devops/
├── scripts/
│   └── lib/             # Shared bash libraries
│       ├── logging.sh
│       ├── exit-codes.sh
│       ├── git-utils.sh
│       ├── path-utils.sh
│       └── hash-utils.sh
├── compose/             # Docker Compose profiles
├── helm/                # Helm charts
└── docker/              # Dockerfiles

Getting Started

Running Workflows Locally

# Run test matrix locally
./devops/scripts/test-local.sh

# Validate compose files
./devops/scripts/validate-compose.sh

# Run a specific test category
./.gitea/scripts/test/run-test-category.sh Unit

Triggering Manual Workflows

# Via Gitea UI: Actions → Workflow → Run workflow

# Or via API:
curl -X POST \
  -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/repos/owner/repo/actions/workflows/rollback.yml/dispatches" \
  -d '{"ref":"main","inputs":{"environment":"staging","version":"v2025.12.0"}}'

Creating a Release

1. Module Release:

   git tag module-authority-v1.2.3
   git push origin module-authority-v1.2.3
   

2. Suite Release:

   git tag suite-2026.04
   git push origin suite-2026.04
   

3. Bundle Release:

   git tag v2025.12.1
   git push origin v2025.12.1
   

Related Documentation

• Workflow Triggers Deep Dive
• Release Pipeline Details
• Security Scanning Guide
• SARIF Integration Guide
• Build-Time DSSE Attestation Walkthrough
• Test Strategy
• CI Recipes
• CI Architecture
• Path Filters Reference
• Smart-Diff Scoring Configuration
• CI Quality Gates

Metrics & Monitoring

The targets below are the pipeline’s service-level objectives. Live workflow runs, test artifacts, and coverage reports are surfaced in the Gitea Actions UI for the repository (.gitea/workflows/); they are not part of this documentation tree.