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 — the “Active Workflows” table is generated from .gitea/workflows/ on every change; the archived-design sections below were 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 workflows with different file names; the generated table states the current count. 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 generated by tools/scripts/generate/workflow-triggers.py and is the list of what actually triggers today. The repo-hygiene lane runs it with --check on every change.
• 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 table between the generated-block markers is written by tools/scripts/generate/workflow-triggers.py from every .gitea/workflows/*.yml file and from tools/scripts/validate/ci-lane-input-sets.json. Do not edit it by hand: change the workflow, run python3 tools/scripts/generate/workflow-triggers.py, and commit both. repo-hygiene-verify.yml runs the generator with --check on every pull request and every push to main, and fails when the committed table differs from the workflows.

How to read the cells:

• PR and Main push: ❌ means no trigger for that event. ✅ means the trigger is unfiltered. ✅* means a paths allow-list gates it. ✅‡ means a paths-ignore list gates it. A push trigger on branches other than main, or on tags, names them in the cell.
• Every ✅* cell, PR or Main push, is an allow-list that is generated, not hand-kept. tools/scripts/generate/ci-lane-allowlists.py derives it from the lane’s ProjectReference closure, including the MSBuild props and NuGet configuration each project reads, and from the Dockerfile, solution or go.mod the lane builds. A lane that has both triggers carries the same derived list under each. The hygiene gate re-derives every list on every push and fails when a committed list differs, or when a pull_request allow-list has no derivation.
• A ✅‡ cell ignores only trees the lane’s scripts never read, for example sprint boards under docs/implplan/. A change touching nothing else skips the lane.
• A lane that pushes to main is never filtered more narrowly on PR than on Main push. It runs the same scripts on either event, so its PR trigger is unfiltered, ignores only trees its push list ignores, or carries the same derived allow-list.
• Schedule (UTC) lists every cron. Manual is workflow_dispatch, with its input names.
• Input set is the lane’s filter in tools/scripts/validate/ci-lane-input-sets.json. That file records, for every push-to-main lane, what its scripts read, which trees it ignores and why, and why a lane stays unfiltered. A lane that filters its PR trigger but does not push to main has a record under pullRequestLanes, shown with (PR). tools/scripts/validate/check-ci-paths-ignore.sh checks both on every push. The generator refuses to write a row whose recorded filter disagrees with the workflow, and a filtered lane that has no record.
• Workflow name:is the display name the forge shows for the run.

61 active workflow files; 38 push to main. Generated from .gitea/workflows/*.yml and tools/scripts/validate/ci-lane-input-sets.json.

Present but never scheduled by Gitea (.disabled suffix): _deprecated-concelier-ci.yml.disabled, _deprecated-concelier-tests.yml.disabled.

Notes:

• .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)