Workflow Triggers & Dependencies

Reference for Stella Ops CI/CD workflow triggering rules and dependency chains. Audience: engineers who need to know which workflow runs for a given event, and how the job graphs depend on one another.

STATUS — verify against the repo before relying on this page (reconciled 2026-05-30). The active CI tree (.gitea/workflows/) does not match most of the tables and dependency diagrams below. On 2026-02-01 all 118 original workflow files were moved to .gitea/workflows-archived/ (see .gitea/README.md), and active CI has since been rebuilt as a different, granular per-concern set of ~32 workflows with different file names. As a result:

• The “Complete Trigger Matrix”, “Dependency Chains”, “Master Trigger Configuration”, “Trigger Decision Tree”, and “Smart Dependency Cascading” sections describe the archived/superseded monolithic CI design (build-test-deploy.yml, test-matrix.yml, release-suite.yml, release.yml, module-publish.yml, cli-build.yml, rollback.yml, promote.yml, etc.). Those files live under .gitea/workflows-archived/ and are not wired to any active trigger — they only run via act or the local-ci-verify.yml dry-run harness. Treat those sections as historical reference for the archived catalog, not as a description of what runs today.
• The “Active Workflows (current .gitea/workflows/)” table immediately below is the authoritative list of what actually triggers today.
• The generic syntax sections (Trigger Types, Conditional Execution Patterns, Path Filters Reference, Tag Patterns Reference, Workflow Inputs Reference, Best Practices, Troubleshooting) remain valid as Gitea/GitHub Actions syntax references and are not workflow-specific.

Source of truth: .gitea/workflows/*.yml (active) and .gitea/workflows-archived/*.yml (archived) in the main repo. This doc carries no auth-scope claims, so the scope catalog (StellaOpsScopes.cs) does not apply here.

Active Workflows (current .gitea/workflows/)

The following is the authoritative set of workflows that actually trigger today (reconciled 2026-05-30 against .gitea/workflows/). Filenames differ entirely from the archived catalog documented later in this page. The Manual column is workflow_dispatch. A ✅* PR/push cell means the trigger is gated by paths filters scoped to that workflow’s owning module(s) plus its own workflow file; ✅ (no asterisk) means unfiltered for that event.

Notes:

• Two disabled module workflows also sit in .gitea/workflows/ as _deprecated-concelier-ci.yml.disabled and _deprecated-concelier-tests.yml.disabled (the .disabled suffix means Gitea never schedules them).
• .gitea/workflow-templates/ holds copy-me templates that are not executed.
• The active set is curated for the resource-constrained Gitea host; several lanes (dotnet-*, fe-e2e-tests) are deliberately workflow_dispatch-only after the 2026-05-14 OOM incident — see the comments at the top of those files.

Trigger Types Overview

1. Push Triggers

Workflows triggered by commits pushed to branches.

on:
  push:
    branches: [main, develop]     # Branch filter
    paths:                        # Path filter (optional)
      - 'src/**'
    paths-ignore:                 # Exclude paths (optional)
      - 'docs/**'
    tags:                         # Tag filter (for releases)
      - 'v*'

2. Pull Request Triggers

Workflows triggered by PR events.

on:
  pull_request:
    branches: [main, develop]     # Target branch filter
    types: [opened, synchronize, reopened]  # Event types
    paths:
      - 'src/**'

3. Schedule Triggers

Cron-based scheduled execution.

on:
  schedule:
    - cron: '0 5 * * *'   # Daily at 5 AM UTC
    - cron: '0 2 * * 0'   # Weekly Sunday at 2 AM UTC

4. Manual Triggers

On-demand workflow execution with inputs.

on:
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options: [staging, production]
      dry_run:
        type: boolean
        default: false

5. Workflow Call (Reusable)

Called by other workflows.

on:
  workflow_call:
    inputs:
      category:
        type: string
        required: true

Complete Trigger Matrix

ARCHIVED-DESIGN REFERENCE. Every workflow named in this section now lives in .gitea/workflows-archived/ and does not trigger in active CI (see the status banner and the “Active Workflows” table above). Specific corrections to the original claims are inlined below; the tables are retained as a record of the archived design. Verified against the archived files on 2026-05-30: the trigger details (branches, path filters, cron, tag patterns) below are broadly accurate for the archived workflow, except where flagged “[CORRECTION]”.

PR-Gating Workflows (Always Run on PR — when active)

Main Branch Only Workflows

Tag-Triggered Workflows

Scheduled Workflows

Manual-Only Workflows

Dependency Chains

ARCHIVED-DESIGN REFERENCE. build-test-deploy.yml, test-matrix.yml, and release-suite.yml are all in .gitea/workflows-archived/. The job graphs below reflect those archived workflows and do not represent any active pipeline. The active CI has no monolithic build→test→deploy or suite-release pipeline (see the status banner and “Active Workflows” table above).

Build → Test → Deploy Pipeline

┌─────────────────────────────────────────────────────────────────┐
│                    build-test-deploy.yml                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  profile-validation ─────────────────────────────────┐          │
│       │                                              │          │
│       ▼                                              │          │
│  build-test ─────────────────────────────────────────┤          │
│       │ (CLI, Concelier, Authority, Scanner, etc.)   │          │
│       │                                              │          │
│       ▼                                              │          │
│  quality-gates ──────────────────────────────────────┤          │
│       │ (Reachability, TTFS, Performance SLOs)       │          │
│       │                                              │          │
│       ▼                                              │          │
│  security-testing (PR label or schedule) ────────────┤          │
│       │                                              │          │
│       ▼                                              │          │
│  sealed-mode-ci ─────────────────────────────────────┤          │
│       │                                              │          │
│       ▼                                              │          │
│  docs ───────────────────────────────────────────────┤          │
│       │                                              │          │
│       ▼                                              │          │
│  scanner-perf ───────────────────────────────────────┘          │
│       │                                                         │
│       ▼                                                         │
│  deploy (main branch only OR workflow_dispatch)                 │
│       │                                                         │
│       ▼                                                         │
│  summary                                                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Test Matrix Pipeline

┌─────────────────────────────────────────────────────────────────┐
│                      test-matrix.yml                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  discover ─────────────────────────────────────────────────┐    │
│       │ (Find all *.Tests.csproj files)                    │    │
│       │                                                    │    │
│       ├───▶ pr-gating-tests (Matrix: 5 categories)         │    │
│       │         ├── Unit                                   │    │
│       │         ├── Architecture                           │    │
│       │         ├── Contract                               │    │
│       │         ├── Security                               │    │
│       │         └── Golden                                 │    │
│       │                                                    │    │
│       ├───▶ integration (PostgreSQL service)               │    │
│       │                                                    │    │
│       └───▶ extended-tests (schedule or manual)            │    │
│                 ├── Performance                            │    │
│                 ├── Benchmark                              │    │
│                 ├── AirGap                                 │    │
│                 ├── Chaos                                  │    │
│                 ├── Determinism                            │    │
│                 ├── Resilience                             │    │
│                 └── Observability                          │    │
│                                                    │       │    │
│       ◀────────────────────────────────────────────┘       │    │
│       │                                                    │    │
│       ▼                                                    │    │
│  summary ◀─────────────────────────────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Suite Release Pipeline

┌─────────────────────────────────────────────────────────────────┐
│                    release-suite.yml                             │
│                  (suite-* tag OR manual)                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  parse-tag (if push event) ────────────────────────────────┐    │
│       │                                                    │    │
│       ▼                                                    │    │
│  validate ─────────────────────────────────────────────────┤    │
│       │                                                    │    │
│       ▼                                                    │    │
│  test-gate (optional, skip with skip_tests=true) ──────────┤    │
│       │                                                    │    │
│       ├───▶ build-modules (Matrix: 9 modules)              │    │
│       │         ├── Authority                              │    │
│       │         ├── Scanner                                │    │
│       │         ├── Concelier                              │    │
│       │         ├── Excititor                              │    │
│       │         ├── SbomService                            │    │
│       │         ├── EvidenceLocker                         │    │
│       │         ├── Policy                                 │    │
│       │         ├── Attestor                               │    │
│       │         └── VexLens                                │    │
│       │                                                    │    │
│       ├───▶ build-containers (Matrix: 9 images)            │    │
│       │                                                    │    │
│       ├───▶ build-cli (Matrix: 5 runtimes)                 │    │
│       │         ├── linux-x64                              │    │
│       │         ├── linux-arm64                            │    │
│       │         ├── win-x64                                │    │
│       │         ├── osx-x64                                │    │
│       │         └── osx-arm64                              │    │
│       │                                                    │    │
│       └───▶ build-helm                                     │    │
│                                                            │    │
│       ◀────────────────────────────────────────────────────┘    │
│       │                                                         │
│       ▼                                                         │
│  release-manifest ─────────────────────────────────────────┐    │
│       │                                                    │    │
│       ├───▶ generate-changelog                             │    │
│       ├───▶ generate-suite-docs                            │    │
│       └───▶ generate-compose                               │    │
│                                                            │    │
│       ◀────────────────────────────────────────────────────┘    │
│       │                                                         │
│       ▼                                                         │
│  create-release ───────────────────────────────────────────┐    │
│       │                                                    │    │
│       ▼                                                    │    │
│  commit-docs ──────────────────────────────────────────────┤    │
│       │                                                    │    │
│       ▼                                                    │    │
│  summary ◀─────────────────────────────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Conditional Execution Patterns

Branch-Based Conditions

# Deploy only on main branch
deploy:
  if: github.ref == 'refs/heads/main'

# Run on main or develop
if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop'

# Skip on release branches
if: "!startsWith(github.ref, 'refs/heads/release/')"

Event-Based Conditions

# Different behavior based on trigger
steps:
  - name: Full scan (schedule)
    if: github.event_name == 'schedule'
    run: ./scan.sh --full

  - name: Quick scan (PR)
    if: github.event_name == 'pull_request'
    run: ./scan.sh --quick

Input-Based Conditions

# Run extended tests if requested
extended-tests:
  if: >-
    github.event_name == 'schedule' ||
    github.event.inputs.include_performance == 'true' ||
    github.event.inputs.include_benchmark == 'true'

Failure-Based Conditions

# Run cleanup on failure
cleanup:
  if: failure()

# Run notification always
notify:
  if: always()

# Run only on success
deploy:
  if: success()

Complex Conditions

# Deploy gate: multiple conditions
deploy:
  if: >-
    needs.build-test.result == 'success' &&
    needs.docs.result == 'success' &&
    needs.scanner-perf.result == 'success' &&
    ((github.event_name == 'push' && github.ref == 'refs/heads/main') ||
     github.event_name == 'workflow_dispatch')

Path Filters Reference

Common Path Patterns

Path Filter Examples

# Source code changes only
paths:
  - 'src/**'
  - '!src/**/*.md'    # Exclude markdown in src

# Documentation only
paths:
  - 'docs/**'
  - '*.md'
  - 'scripts/render_docs.py'

# Security-relevant files
paths:
  - 'src/**/*.cs'
  - 'src/**/*.csproj'
  - '**/Dockerfile*'
  - '.gitea/workflows/sast-scan.yml'

# Dependency files
paths:
  - 'src/Directory.Packages.props'
  - '**/package.json'
  - '**/package-lock.json'
  - '**/*.csproj'

Tag Patterns Reference

Semantic Version Tags

# Standard releases
tags:
  - 'v*'           # v1.0.0, v2025.12.1, v2025.12.0-edge

# Channel-specific
tags:
  - 'v*-edge'      # v2025.12.0-edge
  - 'v*-stable'    # v2025.12.0-stable
  - 'v*-lts'       # v2025.12.0-lts

Suite Tags

tags:
  - 'suite-*'      # suite-2026.04, suite-2026.10

Module Tags

tags:
  - 'module-*-v*'  # module-authority-v1.2.3
                   # module-scanner-v2.0.0
                   # module-cli-v3.1.0

Workflow Inputs Reference

Common Input Types

workflow_dispatch:
  inputs:
    # String input
    version:
      description: 'Version to release'
      required: true
      type: string

    # Choice input
    environment:
      description: 'Target environment'
      type: choice
      options:
        - staging
        - production
      default: staging

    # Boolean input
    dry_run:
      description: 'Run without making changes'
      type: boolean
      default: false

    # Multi-select (via string)
    rids:
      description: 'Runtime identifiers (comma-separated)'
      type: string
      default: 'linux-x64,linux-arm64,win-x64'

Accessing Inputs

steps:
  - name: Use input
    run: |
      echo "Version: ${{ github.event.inputs.version }}"
      echo "Environment: ${{ inputs.environment }}"

      if [[ "${{ inputs.dry_run }}" == "true" ]]; then
        echo "Dry run mode"
      fi

Best Practices

1. Minimize PR Workflow Duration

# Use path filters to skip irrelevant runs
paths-ignore:
  - 'docs/**'
  - '*.md'
  - 'LICENSE'

# Use concurrency to cancel outdated runs
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

2. Fail Fast for Critical Issues

strategy:
  fail-fast: true   # Stop all jobs if one fails
  matrix:
    category: [Unit, Integration, Security]

3. Use Matrix for Parallel Execution

strategy:
  matrix:
    include:
      - category: Unit
        timeout: 20
      - category: Integration
        timeout: 45

4. Preserve Artifacts

- uses: actions/upload-artifact@v4
  with:
    name: test-results-${{ matrix.category }}
    path: ./TestResults
    retention-days: 14   # PR artifacts
    # retention-days: 90  # Release artifacts

5. Use Conditional Steps

- name: Deploy (main only)
  if: github.ref == 'refs/heads/main'
  run: ./deploy.sh

- name: Notify on failure
  if: failure()
  run: ./notify-slack.sh

Troubleshooting Triggers

Workflow Not Running

1. Check branch protection rules - Ensure workflow runs are allowed
2. Verify path filters - File changes must match paths patterns
3. Check if conditions - Job may be skipped by condition
4. Review concurrency settings - May be cancelled by concurrent run

Workflow Running Unexpectedly

1. Check paths-ignore- May need to exclude more paths
2. Review schedule - Cron schedule may overlap with events
3. Check tag patterns - Tag may match unexpected pattern

Schedule Not Triggering

1. Verify cron syntax - Use crontab.guru
2. Check workflow file location - Must be on default branch
3. Review repository activity - Inactive repos may have schedules disabled

Trigger Decision Tree

ARCHIVED-DESIGN REFERENCE. This tree maps events to the archived workflow catalog (Category A/B/C labels, release-suite.yml, module-publish.yml, service-release.yml, containers-multiarch.yml, cli-build.yml). None of those tag/branch routes are wired in active CI. [CORRECTION] In the archived catalog, cli-build.yml and containers-multiarch.yml are workflow_dispatch-only — they do not trigger on v*.*.* tags as the On TAG push branch below implies; release.yml is the workflow that consumes v* tags. For live behaviour, consult the “Active Workflows” table at the top of this page.

Use this decision tree to determine which workflows run for each event:

On PUSH to branch:
│
├── Is branch main/develop?
│   ├── YES → Run Category A (PR-Gating) + B (Main-Only) + affected C (Module)
│   └── NO (feature branch) → Skip CI (rely on PR workflow)
│
On PULL REQUEST:
│
├── Check changed paths
│   ├── docs/** only → Skip all (or run docs.yml only)
│   ├── src/** changed → Run Category A + affected C modules
│   └── *.csproj or *.props changed → Run Category A + B (full infrastructure)
│
On TAG push:
│
├── Match tag pattern
│   ├── suite-* → release-suite.yml
│   ├── module-*-v* → module-publish.yml
│   ├── service-*-v* → service-release.yml
│   ├── v*.*.* → containers-multiarch.yml + cli-build.yml
│   └── Other → Ignore
│
On SCHEDULE:
│
└── Run Category E pipelines per cron schedule

Smart Dependency Cascading

ARCHIVED-DESIGN REFERENCE. The *-ci.yml per-module workflows this section’s cascade graph assumes (e.g. scanner-ci.yml) are archived. Active workflows do scope their own paths filters (see each file’s on.pull_request.paths block), but the centralised cascade matrix below was designed for the archived catalog and is not a guaranteed contract in the current .gitea/workflows/ set — verify per active file.

When shared libraries change, dependent module tests must also run:

Dependency Graph

SHARED LIBRARY                    TRIGGERS TESTS FOR
─────────────────────────────────────────────────────────────────
StellaOps.Cryptography*       →   ALL modules (security-critical)
                                  - Scanner, Attestor, Authority
                                  - EvidenceLocker, Signer
                                  - AirGap, Offline tests
                                  - Security test suite

StellaOps.Evidence*           →   Scanner, Attestor, EvidenceLocker
StellaOps.Provenance          →   ExportCenter, SbomService

StellaOps.Infrastructure.*    →   ALL integration tests
StellaOps.Postgres*               (database-dependent modules)

StellaOps.Replay*             →   Scanner, Determinism tests
StellaOps.Determinism             Replay module tests

StellaOps.Verdict             →   Policy, RiskEngine, ReachGraph
StellaOps.DeltaVerdict

StellaOps.Plugin              →   Authority, Scanner, Concelier
                                  (plugin-based modules)

Directory.Build.props         →   ALL modules (build config)
Directory.Packages.props          ALL tests
nuget.config

Cascade Implementation

Each workflow includes paths from its dependencies:

# Example: scanner-ci.yml with cascading
name: Scanner CI
on:
  push:
    branches: [main]
    paths:
      # Direct module paths
      - 'src/Scanner/**'
      - 'src/BinaryIndex/**'
      # Shared library dependencies (cascading)
      - 'src/__Libraries/StellaOps.Evidence*/**'
      - 'src/__Libraries/StellaOps.Cryptography*/**'
      - 'src/__Libraries/StellaOps.Replay*/**'
      - 'src/__Libraries/StellaOps.Provenance/**'
      # Infrastructure (triggers full test)
      - 'Directory.Build.props'
      - 'Directory.Packages.props'

Cascade Matrix Quick Reference

Master Trigger Configuration

ARCHIVED-DESIGN REFERENCE. Every workflow file named in the table below (build-test-deploy.yml, test-matrix.yml, determinism-gate.yml, policy-lint.yml, sast-scan.yml, secrets-scan.yml, container-scan.yml, release-suite.yml, module-publish.yml, service-release.yml, release.yml, cli-build.yml, containers-multiarch.yml, rollback.yml, promote.yml, nightly-regression.yml, renovate.yml, migration-test.yml, the scanner-*/concelier-*/authority-* modules, etc.) is in .gitea/workflows-archived/ and triggers on nothing in active CI. For the live trigger configuration, use the “Active Workflows” table near the top of this page. The table below is retained as a record of the archived design.

[CORRECTION] Some rows never matched even the archived catalog: service-release.yml is documented elsewhere but the corresponding row pattern referenced service-*-v*; determinism-gate.yml’s archived pull_request trigger is types: [closed] (not a standard PR gate), and secrets-scan.yml runs on all pushes (no paths filter). Re-verify any specific cell against the archived .yml before quoting it.

Complete Workflow Trigger Table

Legend: ✅ = with path filter, ✅ = always, ❌ = never*

Related Documentation

• README - CI/CD Overview
• Release Pipelines
• Test Strategy
• Path Filters Reference
• Active workflow definitions: .gitea/workflows/*.yml (main repo) — source of truth for live triggers
• Archived workflow catalog: .gitea/workflows-archived/*.yml and .gitea/README.md (main repo)
• CI/CD troubleshooting: .gitea/docs/troubleshooting.md (main repo)