11 Workflow Details

🔧 Workflow Details

Your comprehensive guide to Zopio's automated workflow ecosystem - Deep-dive into all 13 GitHub Actions workflows, their configurations, triggers, and optimizations. From build automation to security scanning, everything you need to understand our streamlined CI/CD pipeline.

⚡ Quick Reference

Essential workflow commands and status overview

🎯 Workflow Status at a Glance

📊 Total Workflows

13 Active
5 Core workflows
8 Automation workflows

⚡ Performance

40-50% faster builds
Concurrency controls
Smart caching

🔒 Security

4 Security scanners
Daily + PR scans
Multi-layer protection

🤖 Automation

100% automated
Smart PR labeling
Release management

🚀 Quick Commands

# View all workflows
gh workflow list

# Check recent runs
gh run list --limit 10

# Trigger workflow manually
gh workflow run <workflow-name> --ref <branch>

# Watch running workflow
gh run watch

# Cancel workflow
gh run cancel <run-id>

# Re-run failed jobs
gh run rerun --failed

📈 Key Metrics

Metric	Value	Status
Average Build Time	~8-10 min	🟢 Optimized
Security Scan Coverage	100%	🟢 Complete
Automation Level	Full CI/CD	🟢 Automated
Success Rate	>95%	🟢 Reliable

🎯 Workflow Overview

Complete ecosystem of 13 automated workflows

flowchart TB
    subgraph "Core Workflows (5)"
        BUILD[🏗️ Build]
        CI[⚡ CI Pipeline]
        SEC[🛡️ Security]
        REL[📦 Release]
        CHANGE[📝 Changelog]
    end
    
    subgraph "PR Management (3)"
        PRVAL[✅ PR Validation]
        LABEL[🏷️ Auto Label]
        ASSIGN[👤 PR Assignment]
    end
    
    subgraph "Maintenance (3)"
        WELCOME[👋 Welcome]
        STALE[🧹 Stale Management]
        LOCK[🔒 Thread Locking]
    end
    
    subgraph "Utility (2)"
        DOCS[📚 Documentation]
        SETUP[🔧 Setup Node]
    end
    
    subgraph "Triggers"
        PUSH[Push Events]
        PR[Pull Requests]
        SCHEDULE[Scheduled]
        MANUAL[Manual]
    end
    
    PUSH --> BUILD & CI & SEC & REL & CHANGE
    PR --> BUILD & CI & SEC & PRVAL & LABEL & ASSIGN & WELCOME & DOCS
    SCHEDULE --> SEC & STALE & LOCK
    MANUAL --> CHANGE & STALE & LOCK
    
    style BUILD fill:#4ECDC4
    style SEC fill:#FF6B6B
    style REL fill:#95E1D3
    style PUSH fill:#FFD93D
    style PR fill:#6BCF7F

This page provides in-depth documentation for all 13 workflows in the Zopio project, optimized for performance and security.

🏗️ Build Workflows

Comprehensive build and quality assurance workflows

1. Build Workflow (`build.yml`)

Purpose: Comprehensive build, lint, typecheck, and test pipeline for pull requests targeting the main branch.

Key Features:

Full monorepo build with bundle analysis
Environment variable generation for testing
Multi-app configuration (app, web, api)
Artifact storage for bundle analysis

Environment Setup:

# Authentication
CLERK_SECRET_KEY=sk_test_JA==
CLERK_WEBHOOK_SECRET=whsec_test

# Email & Database
RESEND_FROM=test@test.com
DATABASE_URL=postgresql://test:test@localhost:5432/test

# Payments & Monitoring
STRIPE_SECRET_KEY=sk_test
BETTERSTACK_API_KEY=test

# Real-time & CMS
LIVEBLOCKS_SECRET=sk_test
BASEHUB_TOKEN=${{ secrets.BASEHUB_TOKEN }}

Runtime: ~8-10 minutes
Triggers: PRs to main
Artifacts: Bundle analysis reports

2. CI Workflow (`ci.yml`)

Purpose: Fast CI workflow for develop and staging branches focusing on code quality and test coverage.

Parallel Jobs:

Lint: Biome code quality checks
Test: Vitest test suite
Build: Compilation verification
Security: CodeQL analysis

Special Features:

Graceful handling of missing scripts
Frozen lockfile for reproducibility
Concurrency control for efficiency

Runtime: ~5-7 minutes
Triggers: Push/PR to develop, staging
Key Feature: Parallel execution for faster feedback

🔒 Security Workflows

Multi-layered security scanning and vulnerability detection

3. Security Scan (`security.yml`)

Purpose: Unified security scanning combining multiple tools and vulnerability detection methods.

The security workflow includes:

CodeQL for static code analysis
Trivy for dependency vulnerability scanning
TruffleHog for secret detection
Container scanning for Docker images

For complete details on security scanning, vulnerability reporting, and best practices, see the 🛡️ Security Framework.

Runtime: ~12-15 minutes
Triggers: Push/PR + Daily at 2 AM UTC
Coverage: Code analysis, dependencies, secrets, containers

flowchart LR
    subgraph "Security Layers"
        CODEQL[CodeQL<br/>SAST Analysis]
        TRIVY[Trivy<br/>CVE Scanner]
        TRUFFLEHOG[TruffleHog<br/>Secret Scanner]
        CONTAINER[Container<br/>Security]
    end
    
    subgraph "Results"
        SARIF[SARIF Reports]
        ALERTS[Security Alerts]
        BLOCK[Block on Critical]
    end
    
    CODEQL & TRIVY & TRUFFLEHOG & CONTAINER --> SARIF
    SARIF --> ALERTS --> BLOCK
    
    style CODEQL fill:#FF6B6B
    style TRIVY fill:#FFD93D
    style TRUFFLEHOG fill:#4ECDC4
    style CONTAINER fill:#95E1D3

📦 Release & Version Workflows

Automated semantic versioning and package publishing

4. Release Workflow (`release.yml`)

Purpose: Automatically publishes new releases when changes are pushed to main.

Process Flow:

Skip detection (ci skip or skip ci)
Repository preparation with full history
Dependency installation with caching
CLI build with tsup
Auto release with GitHub and NPM

Dependencies:

auto tool for semantic versioning
NPM_TOKEN for package publishing
GH_TOKEN for GitHub operations

Runtime: ~3-5 minutes
Triggers: Push to main
Outputs: NPM package, GitHub release, Git tags

5. Changelog Generation (`changelog.yml`)

Purpose: Automatically generates CHANGELOG.md based on conventional commits.

Configuration:

Preset: Angular
Tag format: v1.2.3
Bot identity: zopio-bot
Includes all releases (release-count: 0)

Runtime: ~2-3 minutes
Triggers: Push to main, Manual dispatch
Output: Updated CHANGELOG.md with semantic versioning

flowchart LR
    MERGE[Merge to main] --> ANALYZE[Analyze Commits]
    ANALYZE --> GENERATE[Generate Changelog]
    GENERATE --> VERSION[Bump Version]
    VERSION --> TAG[Create Tag]
    TAG --> RELEASE[GitHub Release]
    TAG --> NPM[NPM Publish]
    
    style MERGE fill:#FF6B6B,color:#fff
    style TAG fill:#FFD93D
    style NPM fill:#4ECDC4

🤖 PR Management Workflows

Intelligent PR automation and validation systems

6. PR Validation (`pr-validation.yml`)

Purpose: Comprehensive PR validation with multiple checks.

Validation Steps:

Branch Naming:
- Allowed patterns: feat/*, fix/*, release/v*.*.*, etc.
- Protected branches: main, develop, staging
PR Title Format:
- Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
- Optional scopes: api, app, auth, build, etc.
- Subject must not start with uppercase
Size Limits:
- Soft limit: 1000 lines
- Hard limit: 5000 lines
- File limit: 100 files
Breaking Changes:
- Requires documentation if title contains "!"
- Must include migration instructions

Runtime: ~30 seconds
Triggers: PR events (opened, edited, synchronized)
Consolidates: Branch naming, semantic titles, size checks, breaking changes

7. Auto Labeling (`label.yml`)

Purpose: Automatically applies labels based on multiple criteria.

Label Sources:

File paths (via .github/labeler.yml)
PR title parsing (conventional commits)
Priority keywords (critical, urgent)
Breaking changes (! or "breaking")
Community status (non-org members)

Debug Features:

Lists changed files
Shows detected labels
Tracks label application
Retry logic for API calls

Runtime: ~10-15 seconds
Triggers: PR opened/synchronized
Labels Applied: Type, path-based, size, priority, community status

8. PR Assignment (`pr-assignment.yml`)

Purpose: Automatically assigns PRs to authors and relevant reviewers.

Assignment Rules:

Author assignment for tracking

Team assignment based on code ownership:

packages/auth* → core team
packages/database → core team
packages/core|crud|data → core team
security files → core team

Skips draft PRs for reviewer assignment
Preserves manual assignments

Runtime: ~5-10 seconds
Triggers: PR opened, ready for review
Team Integration: Uses CODEOWNERS for smart reviewer assignment

🧹 Maintenance Workflows

Automated repository housekeeping and community management

9. Stale Management (`stale.yml`)

Purpose: Identifies and closes inactive issues/PRs.

Timing Configuration:

Type	Days to Stale	Days to Close	Total
Issues	60	14	74 days
PRs	30	7	37 days

Exemption Labels:

security
pinned
good first issue
help wanted
priority: critical/high
status: blocked/needs discussion

Runtime: ~1-2 minutes
Schedule: Daily at 1 AM UTC
Exemptions: Security, pinned, help wanted, high priority items

10. Thread Locking (`lock-threads.yml`)

Purpose: Prevents necroposting on old, closed items.

Lock Timing:

Issues: 90 days after closing
PRs: 60 days after closing

Messages:

Issues: Encourages opening new issues for related bugs
PRs: Suggests new PR for further contributions

Runtime: ~30 seconds
Schedule: Daily at 2 AM UTC
Purpose: Prevents necroposting on resolved issues

11. Welcome Messages (`welcome.yml`)

Purpose: Welcomes first-time contributors with resources.

Welcome Content:

Personal mention with @username
Links to contributing guidelines
Different messages for issues vs PRs
Resource links and encouragement

Runtime: ~5 seconds
Triggers: First-time issue/PR from new contributors
Personalization: Mentions user by @username

🔧 Utility Workflows

Supporting workflows and reusable components

12. Documentation Validation (`docs.yml`)

Purpose: Lightweight validation for documentation-only changes.

Checks:

Required files: README.md, CHANGELOG.md
Structure validation
Section presence (installation, setup)
Format compliance

Runtime: ~30 seconds
Triggers: PRs with only documentation changes
Purpose: Lightweight validation for docs-only updates

13. Reusable Node Setup (`setup-node.yml`)

Purpose: Centralized Node.js and pnpm setup.

Parameters:

node-version: Default '20'
pnpm-version: Default '10.11.0'
install-deps: Default true
frozen-lockfile: Default true

Usage Example:

jobs:
  example:
    uses: ./.github/workflows/setup-node.yml
    with:
      node-version: '20'
      pnpm-version: '10.11.0'

Usage: Called by other workflows for consistent Node.js setup
Parameters: Configurable Node/pnpm versions, dependency installation
Benefits: Standardized environment, reduced duplication

📊 Workflow Architecture

System design and workflow interactions

🌐 Complete Workflow Ecosystem

flowchart TB
    subgraph "Event Sources"
        DEV[Developer Push]
        PR_EVENT[Pull Request]
        CRON[Scheduled Jobs]
        MANUAL[Manual Trigger]
    end
    
    subgraph "Core Pipeline"
        VALIDATION[PR Validation<br/>✅ Branch naming<br/>✅ Semantic titles<br/>✅ Size limits]
        BUILD[Build Pipeline<br/>🏗️ Full monorepo<br/>🏗️ Bundle analysis<br/>🏗️ Environment setup]
        CI[CI Pipeline<br/>⚡ Parallel jobs<br/>⚡ Quality checks<br/>⚡ Fast feedback]
        SECURITY[Security Scan<br/>🛡️ CodeQL SAST<br/>🛡️ Dependency scan<br/>🛡️ Secret detection]
    end
    
    subgraph "Automation Layer"
        LABEL[Auto Labeling<br/>🏷️ Path-based<br/>🏷️ Type detection<br/>🏷️ Priority marking]
        ASSIGN[PR Assignment<br/>👤 Author assign<br/>👤 CODEOWNERS<br/>👤 Team routing]
        WELCOME[Welcome Bot<br/>👋 First-timer greeting<br/>👋 Resource links<br/>👋 Personalized]
    end
    
    subgraph "Release Pipeline"
        CHANGELOG[Changelog<br/>📝 Conventional commits<br/>📝 Version bumping<br/>📝 Release notes]
        RELEASE[Release<br/>📦 NPM publish<br/>📦 GitHub release<br/>📦 Git tagging]
    end
    
    subgraph "Maintenance"
        STALE[Stale Management<br/>🧹 Issue cleanup<br/>🧹 PR cleanup<br/>🧹 Auto-close]
        LOCK[Thread Locking<br/>🔒 Prevent necropost<br/>🔒 90d/60d delays<br/>🔒 Explanatory msgs]
    end
    
    %% Event routing
    PR_EVENT --> VALIDATION & BUILD & CI & SECURITY & LABEL & ASSIGN & WELCOME
    DEV -->|to protected branches| CI & SECURITY & CHANGELOG & RELEASE
    CRON --> SECURITY & STALE & LOCK
    MANUAL --> CHANGELOG & STALE & LOCK
    
    %% Pipeline flow
    VALIDATION -->|pass| BUILD
    BUILD -->|pass| CI
    CI -->|pass| SECURITY
    SECURITY -->|pass| MERGE{Can Merge?}
    MERGE -->|yes| CHANGELOG & RELEASE
    
    style VALIDATION fill:#FFD93D
    style BUILD fill:#4ECDC4
    style SECURITY fill:#FF6B6B
    style RELEASE fill:#95E1D3
    style MERGE fill:#6BCF7F

🗗️ Workflow Dependencies

🔗 Required Sequences PR Validation → Build → Merge Push to main → Changelog → Release Security scan → SARIF upload → Alerts	⚡ Parallel Executions CI jobs: Lint + Test + Build + Security PR automation: Label + Assign + Welcome Release: NPM + GitHub + Notifications	🔄 Reusable Components setup-node.yml (shared setup) Security scanning (daily + PR) Path filtering (docs exclusion)

🏆 Workflow Best Practices

Concurrency Control: All workflows use concurrency groups to cancel outdated runs
Path Ignoring: Most workflows skip documentation-only changes
Permission Scoping: Minimal permissions requested for security
Error Handling: Graceful failures with informative messages
Caching Strategy: Strategic caching for dependencies and build artifacts

⚡ Performance & Optimization

How we achieved 40-50% faster workflows

🚀 Optimization Strategies

📉 Before Optimization

Average build time: 15-20 min
Duplicate runs: Common
Resource usage: High
Queue bottlenecks: Frequent
Cost: $X per month

📈 After Optimization

Average build time: 8-10 min
Duplicate runs: Eliminated
Resource usage: 40-50% reduction
Queue flow: Smooth
Cost: $0.5X per month

🏁 Key Optimizations

Concurrency Controls
```
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
```
✔️ Automatically cancels outdated runs
✔️ Prevents duplicate executions
✔️ Saves GitHub Actions minutes
Smart Path Filtering
```
paths-ignore:
  - '**/*.md'
  - 'docs/**'
  - 'LICENSE'
```
✔️ Skips workflows for non-code changes
✔️ Reduces unnecessary runs by ~30%
Parallel Job Execution
- Lint, test, build, and security scans run simultaneously
- Matrix strategies for multi-environment testing
- Independent job failures don't block others
Intelligent Caching
- pnpm dependencies cached with smart invalidation
- Build artifacts cached between runs
- Docker layer caching for container builds
- ~70% cache hit rate achieved

📈 Performance Metrics

Workflow	Original Time	Optimized Time	Improvement
Build (main)	~15 min	~8-10 min	40% faster
CI (dev/staging)	~10 min	~5-7 min	45% faster
Security Suite	~20 min	~12-15 min	35% faster
PR Validation	~30 sec	~10 sec	67% faster
Release Process	~8 min	~3-5 min	50% faster

🚨 Troubleshooting

Common issues and solutions for workflow failures

❌ Common Failure Scenarios

Issue	Symptoms	Solution	Prevention
Workflow Not Triggering	No runs appear in Actions	• Check branch filters • Verify path filters • Validate YAML syntax	Use actionlint for validation
Permission Denied	`Resource not accessible`	• Check GITHUB_TOKEN perms • Use pull_request_target • Verify repo settings	Test with minimal permissions
Build Out of Memory	`heap out of memory`	`NODE_OPTIONS=--max-old-space-size=8192`	Monitor bundle size growth
Flaky Tests	Random test failures	Add retry logic with backoff	Fix race conditions
Cache Miss	Slow dependency installs	Check cache key stability	Use semantic cache keys

🔍 Debugging Commands

# Check workflow syntax
actionlint .github/workflows/*.yml

# View recent workflow runs
gh run list --workflow=build.yml --limit 10

# Get detailed logs for specific run
gh run view <run-id> --log

# Download artifacts for analysis
gh run download <run-id> --name bundle-analysis

# Re-run failed jobs only
gh run rerun <run-id> --failed

# Check workflow file content
gh workflow view build.yml

# Monitor live workflow run
gh run watch

📝 Debug Workflow Context

Add this step to any workflow for debugging:

- name: Debug Workflow Context
  run: |
    echo "Event: ${{ github.event_name }}"
    echo "Action: ${{ github.event.action }}"
    echo "Ref: ${{ github.ref }}"
    echo "SHA: ${{ github.sha }}"
    echo "Actor: ${{ github.actor }}"
    echo "Workflow: ${{ github.workflow }}"
    echo "Job: ${{ github.job }}"

🎆 Emergency Procedures

Critical Production Issues:

Create hotfix branch from main
Use [skip ci] in commit message if needed
Merge with emergency review process
Monitor deployment and rollback if needed

Workflow System Outage:

Check GitHub Status
Use manual deployment if critical
Queue fixes for when system recovers
Communicate status to team

🚪 Next Steps

Continue your workflow journey

🚀 Quick Actions

📈 Learn More 🌐 Pipeline Overview - Complete CI/CD flow 🔄 Workflow Diagram - Visual representations 📅 Triggers Matrix - When workflows run 🛡️ Security Framework - Security deep-dive	⚙️ Customize & Extend 🏗️ Workflow Architecture - System design 🤖 Automation Features - Automation capabilities 🌿 Branch Types - Branching strategy ✨ Best Practices - Pro tips

🎯 Getting Started

First Contribution: Start with Quick Start Guide
Understand Branches: Read Branch Overview
Security Setup: Review Branch Protection Rules
Advanced Topics: Explore Automated Dependencies

📚 External Resources

📚 Related Documentation

Complete reference library

📁 Wiki Navigation

🏁 Getting Started 01-Quick-Start 02-Branch-Overview 03-Branch-Types 05-Branch-Protection-Rules	🔄 Workflow Guides 04-Workflow-Diagram 06-Pipeline-Overview 07-Workflow-Triggers-Matrix 13-Workflow-Architecture	🤖 Automation & Security 08-Automated-Dependency-Management 09-Security-Framework 10-Best-Practices 12-Automation-Features

🔗 Cross-References

Workflow Triggers: See Triggers Matrix for complete trigger reference
Security Details: Deep-dive into Security Framework
Visual Flows: Check Workflow Diagram for flowcharts
Performance: Review Pipeline Overview for optimization tips
Branch Strategy: Understand Branch Types for context

🌐 Single Source of Truth

This page serves as the comprehensive reference for all workflow implementations. For:

Visual representations → Workflow Diagram
Trigger details → Triggers Matrix
Security specifics → Security Framework
Quick overviews → Pipeline Overview

💫 Questions about workflows? Check Troubleshooting | Need implementation details? See actual workflow files in .github/workflows/

Performance issues? Review Performance & Optimization | Security concerns? Visit Security Framework

⬆️ Back to Top | ⬅️ Previous: Triggers Matrix | ➡️ Next: Automation Features

Uh oh!

11 Workflow Details

🔧 Workflow Details

📋 Table of Contents

⚡ Quick Reference

🎯 Workflow Status at a Glance

🚀 Quick Commands

📈 Key Metrics

🎯 Workflow Overview

🏗️ Build Workflows

1. Build Workflow (build.yml)

2. CI Workflow (ci.yml)

🔒 Security Workflows

3. Security Scan (security.yml)

📦 Release & Version Workflows

4. Release Workflow (release.yml)

5. Changelog Generation (changelog.yml)

🤖 PR Management Workflows

6. PR Validation (pr-validation.yml)

7. Auto Labeling (label.yml)

8. PR Assignment (pr-assignment.yml)

🧹 Maintenance Workflows

9. Stale Management (stale.yml)

10. Thread Locking (lock-threads.yml)

11. Welcome Messages (welcome.yml)

🔧 Utility Workflows

12. Documentation Validation (docs.yml)

13. Reusable Node Setup (setup-node.yml)

📊 Workflow Architecture

🌐 Complete Workflow Ecosystem

🗗️ Workflow Dependencies

🏆 Workflow Best Practices

⚡ Performance & Optimization

🚀 Optimization Strategies

🏁 Key Optimizations

📈 Performance Metrics

🚨 Troubleshooting

❌ Common Failure Scenarios

🔍 Debugging Commands

📝 Debug Workflow Context

🎆 Emergency Procedures

🚪 Next Steps

🚀 Quick Actions

🎯 Getting Started

📚 External Resources

📚 Related Documentation

📁 Wiki Navigation

🔗 Cross-References

🌐 Single Source of Truth

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

1. Build Workflow (`build.yml`)

2. CI Workflow (`ci.yml`)

3. Security Scan (`security.yml`)

4. Release Workflow (`release.yml`)

5. Changelog Generation (`changelog.yml`)

6. PR Validation (`pr-validation.yml`)

7. Auto Labeling (`label.yml`)

8. PR Assignment (`pr-assignment.yml`)

9. Stale Management (`stale.yml`)

10. Thread Locking (`lock-threads.yml`)

11. Welcome Messages (`welcome.yml`)

12. Documentation Validation (`docs.yml`)

13. Reusable Node Setup (`setup-node.yml`)