07 Workflow Triggers Matrix

📅 Workflow Triggers Matrix

The definitive guide to when and how workflows trigger in Zopio - Your single source of truth for all 13 GitHub Actions workflows, their triggers, schedules, and dependencies. Optimized with concurrency controls for 40-50% faster builds.

📋 Table of Contents

• ⚡ Quick Reference
• 🎯 At a Glance
• 🏗️ Core Workflows
• 🤖 PR Management Workflows
• 🧹 Maintenance Workflows
• 🔧 Utility Workflows
• 📊 Trigger Types Explained
• 🔄 Workflow Dependencies
• ⚙️ Concurrency & Optimization
• 🚀 Performance Metrics
• 🔐 Branch Protection Integration
• 🛠️ Manual Triggers
• 🚨 Troubleshooting
• 📚 Related Documentation

---

⚡ Quick Reference

Essential commands and shortcuts

# View all workflow runs
gh run list --limit 10

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

# Watch a running workflow
gh run watch

# Cancel a workflow
gh run cancel <run-id>

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

---

🎯 At a Glance

All 13 workflows visualized by trigger type

flowchart LR
    subgraph "Event Triggers"
        Push[Push Events]
        PR[Pull Request]
        Schedule[Scheduled]
        Manual[Manual Dispatch]
    end
    
    subgraph "Core Workflows (5)"
        Build[🏗️ build.yml]
        CI[⚡ ci.yml]
        Security[🔒 security.yml]
        Release[📦 release.yml]
        Changelog[📝 changelog.yml]
    end
    
    subgraph "PR Workflows (3)"
        PRVal[✅ pr-validation.yml]
        Label[🏷️ label.yml]
        Assign[👤 pr-assignment.yml]
    end
    
    subgraph "Maintenance (3)"
        Welcome[👋 welcome.yml]
        Stale[🧹 stale.yml]
        Lock[🔒 lock-threads.yml]
    end
    
    subgraph "Utility (2)"
        Docs[📚 docs.yml]
        Setup[🔧 setup-node.yml]
    end
    
    Push --> CI & Security & Release & Changelog
    PR --> Build & CI & Security & PRVal & Label & Assign & Welcome & Docs
    Schedule --> Security & Stale & Lock
    Manual --> Changelog & Stale & Lock
    
    style Push fill:#4ECDC4
    style PR fill:#95E1D3
    style Schedule fill:#FFD93D
    style Manual fill:#FF6B6B

Loading

🎯 Quick Stats

📊 Total Workflows 13 Active

⚡ Optimizations 40-50% faster Concurrency controls

🕐 Scheduled Jobs 3 Daily workflows 2 AM UTC default

🔒 Security Layers 4 Scan types Daily + PR scans

---

🏗️ Core Workflows

Workflow	File	Triggers	Branches/Conditions	Key Features
Build	build.yml	- PR opened - PR synchronized - PR reopened	Target: main	- Full monorepo build - Lint, typecheck, test - Bundle analysis - Environment setup - ⚡ Concurrency: Yes
CI	ci.yml	- Push - Pull request	Target: develop, staging, release/*, v[0-9]*.[0-9]*	- Fast parallel checks - Lint, test, build - 🔒 CodeQL security - Graceful failures - ⚡ Concurrency: Yes
Security	security.yml	- Push - Pull request - Schedule (2 AM UTC)	Target: main, develop, staging	- Comprehensive security scanning - Multiple vulnerability detectors - → Full details - ⚡ Concurrency: Yes
Release	release.yml	- Push	Target: main	- Auto versioning - NPM publishing - GitHub releases - Skip detection ([ci skip]) - ⚡ Concurrency: Yes
Changelog	changelog.yml	- Push - Manual dispatch	Target: main	- Conventional commits - Version tagging - GitHub releases - Auto commits - ⚡ Concurrency: Yes

🤖 PR Management Workflows

Automated PR handling and validation

Workflow	File	Triggers	Conditions	Key Features
PR Validation	pr-validation.yml	- PR opened - PR edited - PR synchronized - PR reopened - 🎯 pull_request_target	All PRs	- Branch naming rules - Semantic titles - Size limits (1K/5K lines) - Breaking changes check - ⚡ Concurrency: Yes
Auto Label	label.yml	- PR opened - PR synchronized	All PRs (via pull_request_target)	- Path-based labels - Type from title - Priority detection - Community marking - 🏷️ 41 labels
Auto Assign	pr-assignment.yml	- PR opened - PR ready for review	All PRs	- Assign to author - Team reviewers - Code ownership - Skip drafts - 👥 CODEOWNERS

🎯 PR Validation Rules

🏛️ Branch Naming Patterns feat/* or feature/* fix/* hotfix/* release/v*.*.* docs/* chore/* test/* refactor/* ci/* build/* perf/* style/* revert/*

📦 Size Limits Soft limit: 1,000 lines Hard limit: 5,000 lines File limit: 100 files 📝 Title Format type(scope): description Examples: feat: add user auth fix(api): resolve timeout docs: update README

🧹 Maintenance Workflows

Automated repository housekeeping

Workflow	File	Triggers	Schedule/Conditions	Key Features
Stale Management	stale.yml	- Schedule - 🎛️ Manual dispatch	Daily at 1 AM UTC	- Issues: 60d → stale - PRs: 30d → stale - Auto close after warning - Label exemptions - 🎯 14d/7d grace period
Lock Threads	lock-threads.yml	- Schedule - 🎛️ Manual dispatch	Daily at 2 AM UTC 🔐 Only for zopiolabs	- Issues: lock after 90d - PRs: lock after 60d - Prevent necroposting - Add explanation - 🔐 Repository check
Welcome	welcome.yml	- Issue opened - PR opened	First-time contributors	- Personal welcome - Resource links - Guidelines - Encouragement - 🎆 Different messages

🏷️ Exemption Labels

Never marked stale: security pinned good first issue help wanted priority: critical priority: high status: blocked

🔧 Utility Workflows

Supporting workflows and reusable components

Workflow	File	Triggers	Purpose
Documentation	docs.yml	- Push - Pull request	When only docs files change Validates documentation structure 📝 Checks: README.md, CHANGELOG.md 📦 Section validation
Setup Node	setup-node.yml	- 🔄 Workflow call	Reusable workflow for Node.js setup Parameters: • node-version: '20' • pnpm-version: '10.11.0' • install-deps: true • frozen-lockfile: true

🔄 Reusable Workflow Example

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

---

📊 Trigger Types Explained

Understanding the 4 main trigger types

📤 Push Events

When they fire: ✅ Direct commits to branches ✅ Merged PRs (on target branch) ✅ Tag creation ✅ Force pushes

Common uses: on: push: branches: - main - develop tags: - 'v[0-9]*.[0-9]*'

🎯 Pull Request Events

Event types: opened - New PR created edited - Title/body changed synchronized - New commits pushed reopened - Closed PR reopened ready_for_review - Draft → Ready

Permission levels: # Standard (read-only) pull_request: types: [opened, synchronize] # Write permissions (for forks) pull_request_target: types: [opened, synchronize]

🕐 Schedule Events

Our scheduled workflows: Security scan: Daily 2 AM UTC Stale management: Daily 1 AM UTC Lock threads: Daily 2 AM UTC

Cron syntax: on: schedule: # Daily at 2 AM UTC - cron: '0 2 * * *' # Weekly on Monday - cron: '0 3 * * 1'

🎛️ Manual Dispatch

Available for: 📝 Changelog generation 🧹 Stale management 🔒 Thread locking

Trigger via CLI: gh workflow run changelog.yml \ --ref main gh workflow run stale.yml \ --ref main

Branch Protection Integration

Required status checks per branch:

Branch	Required Checks
main	- Build - Security Scan - PR Validation
staging	- CI Pipeline - Security Scan
develop	- CI Pipeline

---

🔄 Workflow Dependencies

How workflows interact and depend on each other

flowchart TB
    subgraph "Push to Main"
        PUSH_MAIN[Push to main] --> CHANGELOG[Changelog Generation]
        PUSH_MAIN --> RELEASE[Release Workflow]
        RELEASE --> NPM[NPM Publish]
        RELEASE --> GH_RELEASE[GitHub Release]
        CHANGELOG -.->|provides| GH_RELEASE
    end
    
    subgraph "Pull Request Flow"
        PR_OPEN[PR Opened] --> PR_VAL[PR Validation]
        PR_OPEN --> LABEL[Auto Label]
        PR_OPEN --> ASSIGN[Auto Assign]
        PR_OPEN --> BUILD[Build Workflow]
        PR_OPEN --> CI[CI Pipeline]
        PR_OPEN --> SEC_PR[Security Scan]
        
        PR_VAL -->|must pass| MERGE{Can Merge?}
        BUILD -->|must pass| MERGE
        CI -->|must pass| MERGE
        SEC_PR -->|must pass| MERGE
    end
    
    subgraph "Scheduled Jobs"
        DAILY[Daily Schedule] --> SEC_DAILY[Security Scan]
        DAILY --> STALE[Stale Management]
        DAILY --> LOCK[Lock Threads]
    end
    
    subgraph "First-Time Contributors"
        FIRST_ISSUE[First Issue] --> WELCOME_ISSUE[Welcome Message]
        FIRST_PR[First PR] --> WELCOME_PR[Welcome Message]
    end
    
    style PUSH_MAIN fill:#FF6B6B,color:#fff
    style PR_OPEN fill:#4ECDC4
    style DAILY fill:#FFD93D
    style MERGE fill:#6BCF7F

Loading

🔗 Key Dependencies

📦 Release Chain Push to main Changelog generates Release publishes NPM deploys

✅ PR Requirements Branch naming valid Title semantic All checks pass Reviews complete

🔄 Reusable Components setup-node.yml Used by: CI, Build Standardizes env

---

⚙️ Concurrency & Optimization

How we achieved 40-50% faster workflows

🚀 Concurrency Controls

All major workflows include concurrency management:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Benefits:

• ✅ Automatically cancels outdated runs
• ✅ Prevents duplicate workflow executions
• ✅ Saves GitHub Actions minutes
• ✅ Faster feedback on PRs

📊 Optimization Strategies

Path Filtering paths-ignore: - '**/*.md' - 'docs/**' - 'LICENSE' - '**/*.txt' Skips workflows for non-code changes

Conditional Steps - name: Run expensive check if: github.event_name == 'push' && github.ref == 'refs/heads/main' Only runs when necessary

🎯 Resource Usage

Before Optimization 15-20 min builds Duplicate runs common High Actions usage Queue bottlenecks

After Optimization 8-10 min builds No duplicate runs 40-50% less usage Smooth queue flow

Key Changes Added concurrency Path filtering Parallel jobs Smart caching

---

🚀 Performance Metrics

Typical workflow execution times and optimization tips

⏱️ Average Execution Times

Workflow	Typical Duration	Optimized	Savings
Build (main)	~15 min	~8-10 min	40%
CI Pipeline	~10 min	~5-7 min	45%
Security Suite	~20 min	~12-15 min	35%
PR Validation	~2 min	~30 sec	75%
Release	~8 min	~3-5 min	50%

💡 Performance Tips

DO ✅ Use path filters aggressively Cache dependencies properly Run jobs in parallel Use concurrency groups Skip unnecessary steps

DON'T ❌ Run all tests on docs changes Duplicate workflow logic Use always() unnecessarily Forget cache keys Chain dependent jobs

📈 Monitoring Performance

# Check workflow duration trends
gh run list --workflow=ci.yml --limit 20 \\
  --json durationMs,conclusion \\
  --jq 'map(select(.conclusion==\"success\") | 
  .durationMs/60000) | add/length'

# Find slow jobs
gh run view <run-id> --json jobs \\
  --jq '.jobs | sort_by(.durationMs) | reverse | 
  .[0:3] | map({name, duration: .durationMs/60000})'

---

🔐 Branch Protection Integration

Required status checks for protected branches

🚫 Required Status Checks

Branch	Required Checks	Additional Requirements
🚀 main	• Build workflow • Security scan • PR validation • 2 reviews	• Up-to-date with base • No direct pushes • Admin bypass disabled
🧪 staging	• CI pipeline • Security scan • 1 review	• No force pushes • No deletions
🔧 develop	• CI pipeline • 1 review	• No force pushes • No deletions

🌟 Status Check Details

Build Workflow (main only) Full monorepo compilation Bundle size analysis E2E test suite ~8-10 minutes

CI Pipeline (dev/staging) Fast quality checks Parallel execution Includes CodeQL ~5-7 minutes

---

🛠️ Manual Triggers

How to manually trigger workflows

🎛️ Available for Manual Dispatch

Workflow	Command	Use Case
Changelog	gh workflow run changelog.yml --ref main	Generate changelog on demand
Stale	gh workflow run stale.yml	Clean up stale issues/PRs
Lock Threads	gh workflow run lock-threads.yml	Lock old discussions

💻 GitHub UI Method

1. Go to Actions tab
2. Select workflow from left sidebar
3. Click Run workflow dropdown
4. Select branch and fill inputs
5. Click Run workflow button

🎯 With Parameters

# Run with inputs
gh workflow run changelog.yml \
  --ref main \
  --field version="1.2.3" \
  --field skip-commit="false"

# Run on specific branch
gh workflow run stale.yml \
  --ref feature/cleanup

---

🚨 Troubleshooting

Common workflow issues and solutions

❌ Common Failures

Issue	Symptoms	Solution
Workflow not triggering	No run appears	• Check branch filters • Verify path filters • Check workflow syntax
Concurrency cancellation	Run cancelled automatically	• Expected behavior • Latest push takes priority • Check run history
Permission denied	Error: Resource not accessible	• Check GITHUB_TOKEN permissions • Use pull_request_target for forks • Verify repo settings
Required check missing	Can't merge PR	• Re-run failed workflow • Check branch protection • Verify workflow name
Schedule not running	Cron job inactive	• Must have activity in 60 days • Check cron syntax • Verify default branch

🔍 Debugging Commands

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

# View workflow runs
gh run list --workflow=<name>

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

# Download artifacts
gh run download <run-id>

# Check specific job
gh run view <run-id> --job=<job-id>

💡 Pro Tips

Debug workflow triggers - name: Debug trigger run: | echo "Event: ${{ github.event_name }}" echo "Action: ${{ github.event.action }}" echo "Ref: ${{ github.ref }}"

Skip a workflow run # In commit message git commit -m "docs: update [skip ci]" # Or git commit -m "chore: cleanup [ci skip]"

---

📚 Related Documentation

Where to go next for detailed information

📝 Core References 🏗️ Pipeline Overview - Full CI/CD pipeline guide 🔧 Workflow Details - In-depth workflow documentation 🤖 Automation Features - Automation capabilities

🎨 Visual Guides 🔀 Workflow Diagram - Visual workflow flows 🏗️ Architecture - System design 🌳 Branch Types - Branching strategy

🚀 Quick Links ⚡ Quick Start - Get started 🔒 Protection Rules - Security ✨ Best Practices - Pro tips

🌐 External Resources

• 📖 GitHub Actions Documentation
• 🎯 Workflow Syntax Reference
• 🔍 Actions Marketplace
• 🚀 GitHub CLI Manual

---

💡 This page is the single source of truth for workflow triggers - For implementation details, see Workflow Details

Need help? Check Troubleshooting | Want to optimize? See Performance Metrics

⬆ Back to Top | ⬅ Previous: Pipeline Overview | ➡ Next: Automated Dependencies