04 Workflow Diagram

🔀 Workflow Diagram

Your visual guide to Zopio's development workflow - See how code flows from your feature branch to production, with automated quality gates, security scans, and release processes at every step.

📋 Table of Contents

• 🎯 Overview
• 🌳 Git Flow Diagram
• 🤖 CI/CD Pipeline
• 📊 Workflow Triggers Matrix
• 🔄 PR Lifecycle
• 🚀 Release Automation
• 🛡️ Security Pipeline
• 🏷️ Labeling System
• ⚡ Quick Commands
• 🔧 Troubleshooting
• 🚪 Next Steps

---

🎯 Overview

Our workflow orchestrates 13 GitHub Actions workflows to ensure code quality, security, and smooth deployments:

🏗️ Build & Test CI Pipeline Build verification Type checking Test coverage

🛡️ Security CodeQL analysis Dependency scans Secret detection Daily audits

🤖 Automation Auto-labeling PR assignment Changelog generation Release publishing

🧹 Maintenance Stale management Thread locking Welcome messages Documentation checks

---

🌳 Git Flow Diagram

See how your code travels from development to production

flowchart TD
    subgraph "Feature Development"
        Dev[Developer] -->|git checkout -b| Feature[feat/* branch]
        Feature -->|commits| LocalWork[Local Development]
        LocalWork -->|git push| PR[Pull Request]
    end
    
    subgraph "Integration & Testing"
        PR -->|targets| Develop[🔧 develop]
        PR -->|triggers| CI{CI/CD Pipeline}
        CI -->|runs| Tests[✅ Tests]
        CI -->|runs| Lint[🎨 Linting]
        CI -->|runs| Build[🏗️ Build]
        CI -->|runs| Security[🛡️ Security]
        Tests & Lint & Build & Security -->|all pass| Review[👀 Code Review]
        Review -->|approved| Merge[🔀 Merge to develop]
    end
    
    subgraph "Release Process"
        Develop -->|ready for release| Release[release/v*.*.*]
        Release -->|PR to| Staging[🧪 staging]
        Staging -->|E2E tests| QA[QA Testing]
        QA -->|approved| Main[🚀 main]
        Main -->|triggers| AutoRelease[📦 Auto Release]
        AutoRelease -->|creates| Tag[🏷️ Git Tag]
        AutoRelease -->|generates| Changelog[📝 Changelog]
        AutoRelease -->|publishes| NPM[📦 NPM]
    end
    
    subgraph "Hotfix Flow"
        Prod[Production Issue] -->|urgent| Hotfix[hotfix/*]
        Hotfix -->|PR to| Main
        Hotfix -->|also PR to| Develop
    end
    
    style Feature fill:#4ECDC4,stroke:#333,stroke-width:2px
    style Develop fill:#6BCF7F,stroke:#333,stroke-width:2px
    style Staging fill:#FFD93D,stroke:#333,stroke-width:2px
    style Main fill:#FF6B6B,stroke:#333,stroke-width:2px,color:#fff
    style Hotfix fill:#F38181,stroke:#333,stroke-width:2px
    style AutoRelease fill:#95E1D3,stroke:#333,stroke-width:2px

Loading

---

🤖 CI/CD Pipeline

Automated quality gates for every pull request

flowchart LR
    subgraph "Trigger Events"
        Push[Push to Branch]
        PROpen[PR Opened]
        PRSync[PR Synchronized]
        Schedule[Scheduled]
        Manual[Manual Dispatch]
    end
    
    subgraph "Validation Layer"
        BranchName[Branch Naming]
        PRTitle[PR Title Format]
        PRSize[PR Size Check]
        Breaking[Breaking Changes]
    end
    
    subgraph "Quality Checks"
        Biome[Biome Linting]
        Vitest[Vitest Tests]
        TSC[TypeScript Check]
        BuildCheck[Build Verification]
    end
    
    subgraph "Security Scans"
        CodeQL[CodeQL Analysis]
        Trivy[Dependency Scan]
        TruffleHog[Secret Detection]
    end
    
    subgraph "Automation"
        Labels[Auto-label PR]
        Assign[Assign Author]
        Welcome[Welcome Message]
        Status[Update Status]
    end
    
    PROpen --> BranchName & PRTitle & PRSize
    Push --> Biome & Vitest & TSC & BuildCheck
    Push --> CodeQL & Trivy & TruffleHog
    PROpen --> Labels & Assign & Welcome
    Schedule --> CodeQL & Trivy & TruffleHog
    
    BranchName & PRTitle & PRSize & Breaking -->|must pass| Merge{Can Merge?}
    Biome & Vitest & TSC & BuildCheck -->|must pass| Merge
    CodeQL & Trivy & TruffleHog -->|must pass| Merge
    
    style Push fill:#4ECDC4
    style PROpen fill:#95E1D3
    style Schedule fill:#FFD93D
    style Merge fill:#6BCF7F

Loading

---

📊 Workflow Triggers Matrix

When each workflow runs and what triggers it

Workflow	Push main	Push develop	Push staging	Pull Request	Schedule	Manual	Purpose
🏗️ build.yml	❌	❌	❌	✅ (to main)	❌	❌	Comprehensive PR validation
🚀 ci.yml	❌	✅	✅	✅ (dev/staging)	❌	❌	Fast CI checks
📝 changelog.yml	✅	❌	❌	❌	❌	✅	Generate changelog
📦 release.yml	✅	❌	❌	❌	❌	❌	Auto-publish releases
🛡️ security.yml	✅	✅	✅	✅	🕐 Daily	❌	Security scanning suite
✅ pr-validation.yml	❌	❌	❌	✅	❌	❌	PR format validation
🏷️ label.yml	❌	❌	❌	✅	❌	❌	Auto-label PRs
👤 pr-assignment.yml	❌	❌	❌	✅	❌	❌	Assign PR author
👋 welcome.yml	❌	❌	❌	✅	❌	❌	Welcome contributors
📚 docs.yml	❌	❌	❌	✅ (docs)	❌	❌	Documentation checks
🧹 stale.yml	❌	❌	❌	❌	🕐 Daily	✅	Mark stale items
🔒 lock-threads.yml	❌	❌	❌	❌	🕐 Daily	✅	Lock old threads

🔑 Key Points

• Concurrency Control: All workflows include duplicate prevention
• Conditional Runs: Some workflows only trigger on specific file changes
• Resource Optimization: 40-50% reduction in GitHub Actions usage

---

🔄 PR Lifecycle

What happens when you open a pull request

stateDiagram-v2
    [*] --> PROpened: Developer opens PR
    
    PROpened --> Validation: Automatic triggers
    state Validation {
        [*] --> BranchCheck: Check branch name
        [*] --> TitleCheck: Check PR title
        [*] --> SizeCheck: Check PR size
        BranchCheck --> Valid
        TitleCheck --> Valid
        SizeCheck --> Valid
    }
    
    Validation --> Labeling: All checks pass
    state Labeling {
        [*] --> TypeLabel: Based on title (feat/fix/docs)
        [*] --> PathLabel: Based on files changed
        [*] --> SizeLabel: Based on lines changed
        TypeLabel --> Labeled
        PathLabel --> Labeled
        SizeLabel --> Labeled
    }
    
    Labeling --> Assignment: Labels applied
    Assignment --> Testing: Author assigned
    
    state Testing {
        [*] --> Lint: Biome linting
        [*] --> Test: Vitest tests
        [*] --> Build: Build check
        [*] --> Security: Security scans
        Lint --> TestsPass
        Test --> TestsPass
        Build --> TestsPass
        Security --> TestsPass
    }
    
    Testing --> Review: All tests pass
    Review --> Approved: Code review complete
    Approved --> Merged: Squash & merge
    Merged --> [*]: PR closed
    
    Validation --> FixRequired: Validation fails
    Testing --> FixRequired: Tests fail
    Review --> FixRequired: Changes requested
    FixRequired --> PROpened: Push fixes

Loading

---

🚀 Release Automation

How releases are automatically created and published

flowchart TD
    subgraph "Release Trigger"
        Merge[PR Merged to main] -->|triggers| Release[release.yml]
    end
    
    subgraph "Changelog Generation"
        Release --> Analyze[Analyze Commits]
        Analyze --> Generate[Generate Changelog]
        Generate --> Version[Bump Version]
        Version --> Commit[Commit Changes]
    end
    
    subgraph "Publishing"
        Commit --> Tag[Create Git Tag]
        Tag --> GHRelease[GitHub Release]
        Tag --> NPM[NPM Publish]
        GHRelease --> Notify[Notify Team]
    end
    
    subgraph "Artifacts"
        GHRelease --> Notes[Release Notes]
        GHRelease --> Assets[Build Assets]
        NPM --> Registry[NPM Registry]
    end
    
    style Merge fill:#FF6B6B,color:#fff
    style Release fill:#95E1D3
    style Tag fill:#FFD93D
    style NPM fill:#4ECDC4

Loading

📦 Version Bumping Rules

Commit Type	Version Bump	Example
fix:	Patch (0.0.X)	1.2.3 → 1.2.4
feat:	Minor (0.X.0)	1.2.3 → 1.3.0
feat!: or BREAKING CHANGE	Major (X.0.0)	1.2.3 → 2.0.0
chore:, docs:, etc.	No bump	1.2.3 → 1.2.3

---

🛡️ Security Pipeline

Multi-layered security scanning for every change

flowchart TB
    subgraph "Security Layers"
        Layer1[Code Analysis]
        Layer2[Dependency Scanning]
        Layer3[Secret Detection]
        Layer4[Container Security]
    end
    
    subgraph "Scanners"
        CodeQL[CodeQL<br/>SAST Analysis]
        Trivy[Trivy<br/>CVE Scanner]
        TruffleHog[TruffleHog<br/>Secret Scanner]
        Container[Container<br/>Scan]
    end
    
    subgraph "Triggers"
        PR[Pull Request]
        Push[Push to Protected]
        Daily[Daily Schedule]
    end
    
    subgraph "Results"
        SARIF[SARIF Reports]
        Alerts[Security Alerts]
        Block[Block Merge]
        Email[Email Notify]
    end
    
    PR & Push & Daily --> Layer1 & Layer2 & Layer3 & Layer4
    Layer1 --> CodeQL
    Layer2 --> Trivy
    Layer3 --> TruffleHog
    Layer4 --> Container
    
    CodeQL & Trivy & TruffleHog & Container --> SARIF
    SARIF --> Alerts
    Alerts -->|critical| Block
    Alerts -->|high| Email
    
    style Layer1 fill:#FF6B6B
    style Layer2 fill:#FFD93D
    style Layer3 fill:#4ECDC4
    style Layer4 fill:#95E1D3

Loading

🔍 Security Check Details

Scanner	What it Finds	When it Runs	Action on Finding
CodeQL	Code vulnerabilities, OWASP issues	PR + Daily	Creates security alert
Trivy	Known CVEs in dependencies	PR + Daily	Blocks if critical
TruffleHog	Exposed secrets, API keys	PR + Daily	Immediate block
Container	Docker image vulnerabilities	On Dockerfile change	Advisory alert

---

🏷️ Labeling System

Automatic PR labeling based on your changes

🎯 Type Labels (from PR title)

PR Title Prefix	Label Applied	Color
feat:	type: feature	🟢 Green
fix:	type: fix	🔴 Red
docs:	type: documentation	🔵 Blue
chore:	type: chore	🟡 Yellow
test:	type: test	🟡 Yellow
refactor:	type: refactor	🟣 Purple
perf:	type: performance	🟠 Orange
ci:	type: ci	🟢 Green
build:	type: build	🔵 Blue

📁 Path-based Labels

Files Changed	Label Applied
/packages/core/*	package: core
/packages/auth*	package: auth
/apps/web/*	app: web
*.md	documentation
package.json	dependencies
*.test.ts	testing
.github/workflows/*	ci/cd

📏 Size Labels

Lines Changed	Label	Description
< 10	size: XS	Trivial change
10-100	size: S	Small change
100-500	size: M	Medium change
500-1000	size: L	Large change
> 1000	size: XL	Very large change

---

⚡ Quick Commands

Common workflow commands

🚀 Development Flow

# Start a new feature
git checkout -b feat/awesome-feature develop
git push -u origin feat/awesome-feature

# Create PR (GitHub CLI)
gh pr create --base develop --title "feat: add awesome feature"

# Check workflow status
gh run list --limit 5
gh run view

# View PR checks
gh pr checks

🔍 Debugging Workflows

# View workflow runs
gh workflow list
gh workflow view ci.yml

# Check specific run
gh run view --log
gh run view --log-failed

# Re-run failed workflows
gh run rerun

📦 Release Commands

# Create release branch
git checkout -b release/v1.2.0 develop
git push -u origin release/v1.2.0

# After merge to main, release is automatic
# But you can trigger changelog manually
gh workflow run changelog.yml

---

🔧 Troubleshooting

Common workflow issues and solutions

❌ PR Validation Failures

Error	Cause	Solution
"Invalid branch name"	Wrong naming pattern	Rename to feat/*, fix/*, etc.
"PR title must be semantic"	Non-conventional title	Use format: type: description
"PR too large"	> 1000 lines changed	Split into smaller PRs
"Breaking change needs docs"	! without description	Add "Breaking Changes" section

🚫 CI/CD Failures

# Biome linting errors
pnpm lint:fix

# TypeScript errors
pnpm typecheck

# Test failures
pnpm test:watch

# Build errors
pnpm build

🛡️ Security Scan Issues

Issue	Severity	Action Required
Secret detected	🔴 Critical	Remove immediately, rotate secret
High CVE in dependency	🟠 High	Update dependency or add override
CodeQL warning	🟡 Medium	Review and fix if valid

---

🚪 Next Steps

Now that you understand the workflow, explore these areas:

📚 Learn More 🌳 Branch Types - All branch patterns 🛡️ Protection Rules - Merge requirements 🤖 Pipeline Overview - CI/CD details

🚀 Get Started ⚡ Quick Start - Your first PR ✨ Best Practices - Pro tips 📊 Triggers Matrix - Detailed triggers

---

Questions? Check GitHub Discussions | Workflow issues? See Actions tab

⬆ Back to Top | ⬅ Previous: Branch Types | ➡ Next: Protection Rules