Workflow Architecture

Overview

Important (v2): All workflows MUST be in .gitea/workflows/ only. Gitea Actions does not run workflows from .gitea/workflows/. Having files in .gitea/workflows/ creates ghost queued runs that block the runner.

This document explains the workflow architecture used across Moko Consulting repositories, including the hierarchy, design patterns, reusable workflow patterns, and decision-making processes for workflow selection.

Purpose

This architecture guide provides:

Understanding: Clear mental model of workflow organization
Guidance: Decision trees for workflow selection
Patterns: Reusable patterns and best practices
Relationships: How workflows interact and depend on each other
Evolution: How to extend and improve the workflow architecture

Three-Tier Workflow Architecture

Moko Consulting uses a three-tier architecture for Gitea Actions workflows:

┌─────────────────────────────────────────────────────────────┐
│ Tier 1: Organization-Wide Reusable Workflows               │
│ Location: .github-private repository                        │
│ Visibility: Private                                         │
│ Purpose: Shared across all organization repositories        │
│ Examples: Deployment, compliance audits, security scanning  │
└─────────────────────────────────────────────────────────────┘
                          ↓ (called by)
┌─────────────────────────────────────────────────────────────┐
│ Tier 2: Public Reusable Workflows                          │
│ Location: moko-platform repository                          │
│ Visibility: Public                                          │
│ Purpose: Templates and patterns for community use           │
│ Examples: CI validation, build automation, health checks    │
└─────────────────────────────────────────────────────────────┘
                          ↓ (called by)
┌─────────────────────────────────────────────────────────────┐
│ Tier 3: Local Workflows                                    │
│ Location: Individual repository .gitea/workflows/         │
│ Visibility: Matches repository visibility                   │
│ Purpose: Repository-specific automation                    │
│ Examples: Project builds, tests, custom deployments        │
└─────────────────────────────────────────────────────────────┘