metabuilder/.github/workflows

GitHub Workflows Documentation

This directory contains automated workflows for CI/CD, code quality, and comprehensive AI-assisted development throughout the entire SDLC.

🚦 Enterprise Gated Tree Workflow

MetaBuilder uses an Enterprise Gated Tree Workflow that ensures all code changes pass through multiple validation gates before being merged and deployed.

📖 Complete Guide: Enterprise Gated Workflow Documentation

Quick Overview

All PRs must pass through 5 sequential gates:

1. Gate 1: Code Quality - Prisma, TypeScript, Lint, Security
2. Gate 2: Testing - Unit, E2E, DBAL Daemon tests
3. Gate 3: Build & Package - Application build, quality metrics
4. Gate 4: Review & Approval - Human code review (1 approval required)
5. Gate 5: Deployment - Staging (auto) → Production (manual approval)

Key Benefits:

• ✅ Sequential gates prevent wasted resources
• ✅ Automatic merge after approval
• ✅ Manual approval required for production
• ✅ Clear visibility of gate status on PRs
• ✅ Audit trail for all deployments

Legacy Workflow Cleanup

Deprecated and Removed (Dec 2025):

• ❌ ci/ci.yml - Replaced by gated-ci.yml (100% redundant)
• ❌ quality/deployment.yml - Replaced by gated-deployment.yml (100% redundant)

Modified:

• ⚡ development.yml - Refactored to remove redundant quality checks, kept unique Copilot features

See Legacy Pipeline Cruft Report for analysis.

🤖 GitHub Copilot Integration

All workflows are designed to work seamlessly with GitHub Copilot to assist throughout the Software Development Lifecycle:

• Planning Phase: Architecture review, PRD alignment, implementation guidance
• Development Phase: Continuous quality feedback, code suggestions, refactoring opportunities
• Testing Phase: Automated code review, security checks, quality validation
• Deployment Phase: Pre-deployment validation, health checks, monitoring
• Maintenance Phase: Issue triage, automated fixes, dependency management

📖 Copilot Instructions: .github/copilot-instructions.md

Workflows Overview

🚦 Enterprise Gated Workflows (New)

1. Enterprise Gated CI/CD Pipeline (gated-ci.yml)

Triggered on: Push to main/master/develop branches, Pull requests

Structure:

• Gate 1: Code Quality (Prisma, TypeScript, Lint, Security)
• Gate 2: Testing (Unit, E2E, DBAL Daemon)
• Gate 3: Build & Package (Build, Quality Metrics)
• Gate 4: Review & Approval (Human review required)

Features:

• Sequential gate execution for efficiency
• Clear gate status reporting on PRs
• Automatic progression through gates
• Summary report with all gate results

Best for: Small to medium teams, straightforward workflows

1a. Enterprise Gated CI/CD Pipeline - Atomic (gated-ci-atomic.yml) 🆕

Triggered on: Push to main/master/develop branches, Pull requests

Structure:

• Gate 1: Code Quality - 7 atomic steps
  • 1.1 Prisma Validation
  • 1.2 TypeScript Check (+ strict mode analysis)
  • 1.3 ESLint (+ any-type detection + ts-ignore detection)
  • 1.4 Security Scan (+ dependency audit)
  • 1.5 File Size Check
  • 1.6 Code Complexity Analysis
  • 1.7 Stub Implementation Detection
• Gate 2: Testing - 3 atomic steps
  • 2.1 Unit Tests (+ coverage analysis)
  • 2.2 E2E Tests
  • 2.3 DBAL Daemon Tests
• Gate 3: Build & Package - 2 atomic steps
  • 3.1 Application Build (+ bundle analysis)
  • 3.2 Quality Metrics
• Gate 4: Review & Approval (Human review required)

Features:

• Atomic validation steps for superior visualization
• Each tool from /tools runs as separate job
• Gate artifacts persisted between steps (30-day retention)
• Granular failure detection
• Parallel execution within gates
• Complete audit trail with JSON artifacts
• Individual step timing and status

Best for: Large teams, enterprise compliance, audit requirements

Documentation: See Atomic Gated Workflow Architecture

2. Enterprise Gated Deployment (gated-deployment.yml)

Triggered on: Push to main/master, Releases, Manual workflow dispatch

Environments:

• Staging: Automatic deployment after merge to main
• Production: Manual approval required

Features:

• Pre-deployment validation (schema, security, size)
• Breaking change detection and warnings
• Environment-specific deployment paths
• Post-deployment health checks
• Automatic deployment tracking issues
• Rollback preparation and procedures

Gate 5: Deployment gate ensures only reviewed code reaches production

🔄 Legacy Workflows (Still Active)

3. CI/CD Workflow (ci/ci.yml) - ❌ REMOVED

Status: Deprecated and removed (Dec 2025)
Reason: 100% functionality superseded by gated-ci.yml

Jobs: Prisma Check, Lint, Build, E2E Tests, Quality Check

Replacement: Use gated-ci.yml for all CI/CD operations Triggered on: Push to main/master/develop branches, Pull requests

Jobs:

• Prisma Check: Validates database schema and generates Prisma client
• Lint: Runs ESLint to check code quality
• Build: Builds the application and uploads artifacts
• E2E Tests: Runs Playwright end-to-end tests
• Quality Check: Checks for console.log statements and TODO comments

4. Automated Code Review (code-review.yml)

Triggered on: Pull request opened, synchronized, or reopened

Features:

• Analyzes code changes for security issues (eval, innerHTML, XSS risks)
• Checks for code quality issues (console.log, debugger, any types)
• Provides suggestions for improvements
• Auto-approves PRs if no blocking issues are found
• Adds appropriate labels (needs-changes, ready-for-review, has-warnings)

Review Criteria:

• ✅ Security vulnerabilities
• ✅ Code quality issues
• ✅ Type safety
• ✅ React best practices
• ✅ File size warnings

5. Auto Merge (auto-merge.yml) - Updated for Gated Workflow

Triggered on: PR approval, CI workflow completion

Features:

• Automatically merges PRs when:
  • PR is approved by reviewers
  • All gates pass (supports both gated and legacy CI checks)
  • No merge conflicts
  • PR is not in draft
• Automatically deletes the branch after successful merge
• Uses squash merge strategy
• Posts comments about merge status
• Updated: Now supports Enterprise Gated CI/CD Pipeline checks

6. Issue Triage (issue-triage.yml)

Triggered on: New issues opened, issues labeled

Features:

• Automatically categorizes and labels issues:
  • Type: bug, enhancement, documentation, testing, security, performance
  • Priority: high, medium, low
  • AI-fixable flag for automated fixes
• Posts welcome message with issue summary
• Suggests automated fix attempts for simple issues
• Can create fix branches automatically with create-pr label

7. PR Management (pr-management.yml)

Triggered on: PR opened, synchronized, labeled

Features:

• Auto-labels PRs based on changed files:
  • workflows, tests, documentation, ui, styling, configuration, dependencies
  • Size labels (small/medium/large)
  • Type labels from PR title (bug, enhancement, refactor, etc.)
• Validates PR descriptions
• Links related issues automatically
• Posts comments on related issues

8. Merge Conflict Check (merge-conflict-check.yml)

Triggered on: PR opened/synchronized, push to main/master

Features:

• Detects merge conflicts
• Posts comment mentioning @copilot to resolve
• Adds/removes merge-conflict label
• Fails CI if conflicts exist

9. Planning & Design (planning.yml) 🆕

Triggered on: Issues opened or labeled with enhancement/feature-request

Features:

• Architecture Review: Analyzes feature requests against architectural principles
• PRD Alignment Check: Ensures new features align with project mission
• Implementation Suggestions: Provides step-by-step implementation guidance
• Validates declarative-first approach
• Checks multi-tenant and permission considerations
• Creates design checklists for feature implementation
• @copilot integration for architecture guidance

SDLC Phase: Planning & Design

10. Development Assistance (development.yml) 🆕 - Refactored

Triggered on: Pull request updates, @copilot mentions

Features:

• Architectural Compliance Feedback: Monitors declarative ratio and component sizes
• @copilot Interaction Handler: Responds to @copilot mentions with context-aware guidance
• Refactoring Suggestions: Identifies opportunities for improvement
• Provides architectural reminders and best practices

Note: Refactored to remove redundant quality checks (lint/build now in gated-ci.yml)

SDLC Phase: Development

11. Deployment & Monitoring (deployment.yml) - ❌ REMOVED

Status: Deprecated and removed (Dec 2025)
Reason: 100% functionality superseded by gated-deployment.yml with improvements

Jobs: Pre-Deployment Validation, Deployment Summary, Post-Deployment Health Checks

Replacement: Use gated-deployment.yml for all deployment operations

12. Code Size Limits (size-limits.yml)

Triggered on: Pull requests, pushes to main (when source files change)

Features:

• Enforces file size limits and posts PR comments on violations
• Uploads a size report artifact
• Monitors frontends/nextjs/src/** and runs scripts/enforce-size-limits.ts from frontends/nextjs

SDLC Coverage

🎯 Complete Lifecycle Support

┌─────────────┐
│  Planning   │ ← planning.yml (Architecture Review, PRD Check)
└──────┬──────┘
       ↓
┌─────────────┐
│ Development │ ← development.yml (Quality Feedback, Refactoring)
└──────┬──────┘
       ↓
┌─────────────┐
│   Testing   │ ← ci.yml, code-review.yml (Lint, Build, E2E)
└──────┬──────┘
       ↓
┌─────────────┐
│ Integration │ ← pr-management.yml, auto-merge.yml
└──────┬──────┘
       ↓
┌─────────────┐
│ Deployment  │ ← deployment.yml (Validation, Health Checks)
└──────┬──────┘
       ↓
┌─────────────┐
│ Maintenance │ ← issue-triage.yml, dependabot.yml
└─────────────┘

Labels Used

Automated Labels

• bug - Bug fixes
• enhancement - New features
• feature-request - Proposed new features
• ready-to-implement - Features ready for development
• documentation - Documentation changes
• tests - Test-related changes
• security - Security issues
• performance - Performance improvements
• needs-changes - PR requires changes
• ready-for-review - PR is ready for review
• has-warnings - PR has warnings to address
• large-pr - PR with many changes
• size: small/medium/large - PR size indicators
• ai-fixable - Issues that can be auto-fixed
• good first issue - Good for newcomers
• priority: high/medium/low - Issue priority
• merge-conflict - PR has merge conflicts
• auto-fix - Request automated fix
• create-pr - Create fix PR for issue
• deployment - Deployment tracking
• monitoring - Monitoring and observability
• dependencies - Dependency updates
• refactor - Code refactoring
• chore - Maintenance tasks
• workflows - Workflow changes
• ui - UI/UX changes
• styling - CSS/Tailwind changes
• configuration - Config file changes

Configuration

ESLint

The project uses ESLint with TypeScript support and React-specific rules:

• File: eslint.config.js
• Strict type checking (warnings for gradual adoption)
• React hooks validation
• Code quality rules

Playwright E2E Tests

• Configuration: playwright.config.ts
• Tests directory: e2e/
• Runs on Chromium browser
• Tests include:
  • Login functionality
  • Navigation
  • CRUD operations
  • Form interactions

Usage

Working with GitHub Copilot

In Issues:

@copilot implement this issue
@copilot review the architecture
@copilot suggest testing strategy
@copilot help with this

In Pull Requests:

• Automated feedback on every push
• Continuous quality metrics
• Refactoring suggestions
• Architectural compliance checks

In Your IDE:

• Reference .github/copilot-instructions.md for context
• Use docs/getting-started/PRD.md for feature context
• Follow existing patterns in /packages/
• Ask Copilot about architectural decisions

Testing Workflows Locally with Act

Before pushing to GitHub, test workflows locally using act:

# Quick diagnostics (no act required)
./scripts/diagnose-workflows.sh

# Interactive workflow testing
./scripts/test-workflows.sh

# Or use act directly
act -l                    # List all workflows
act push                  # Run CI pipeline
act -j lint              # Test linting job
act -j build             # Test build job

📖 See ACT_TESTING.md for comprehensive act testing guide

Running Locally

# Run linter
bun run lint

# Fix linting issues automatically
bun run lint:fix

# Run e2e tests
bun run test:e2e

# Run e2e tests with UI
bun run test:e2e:ui

# Run e2e tests in headed mode
bun run test:e2e:headed

# Build the project
bun run build

Triggering Workflows

Planning Phase:

1. Create issue with enhancement or feature-request label
2. Automated architecture review and PRD alignment check
3. Add ready-to-implement label for implementation guidance
4. Follow suggested step-by-step plan

Development Phase:

1. Create feature branch: git checkout -b feature/issue-X
2. Push changes - triggers continuous quality feedback
3. Get real-time metrics on declarative ratio, component sizes
4. Mention @copilot in commits/PRs for specific help
5. Review refactoring suggestions

Testing & Review Phase:

1. Open PR - automatically reviewed, labeled, and validated
2. Address any architectural compliance issues
3. Get approval + pass tests
4. Automatically merged and branch deleted

Deployment Phase:

1. Merge to main - triggers pre-deployment validation
2. Create release - generates deployment notes and tracking issue
3. Post-deployment health checks run automatically
4. Monitor deployment tracking issue for 48 hours

Maintenance Phase:

1. Security audits run on every deployment
2. Dependabot creates automated dependency PRs
3. Issue triage handles new bug reports
4. @copilot assists with fixes and improvements

For Issues:

1. Create an issue - automatically triaged and labeled
2. Add enhancement label - triggers architecture review
3. Add ready-to-implement label - get implementation guidance
4. Add auto-fix label to request automated fix
5. Add create-pr label to create a fix branch
6. Mention @copilot for specific assistance

For PRs:

1. Open a PR - automatically reviewed, labeled, and validated
2. Push changes - triggers CI/CD pipeline and quality feedback
3. Get approval + pass tests - automatically merged and branch deleted
4. Receive continuous refactoring suggestions

Working with AI Assistance

In Issues & PRs:

• Mention @copilot implement this - Get implementation guidance
• Mention @copilot review - Request code review
• Mention @copilot architecture - Get architectural guidance
• Mention @copilot test - Get testing help
• Mention @copilot fix this issue - Request automated fix

In Your IDE:

• Use GitHub Copilot extension with context from .github/copilot-instructions.md
• Reference docs/getting-started/PRD.md when prompting for features
• Follow patterns from existing packages
• Ask about architectural decisions before implementing

Automated Copilot Features:

• Architecture review on feature requests
• Continuous quality feedback during development
• Refactoring opportunity detection
• PRD alignment checking
• Implementation step-by-step guidance

Best Practices

For Development

1. Follow declarative-first principles - Prefer JSON + Lua over TypeScript
2. Keep components under 150 LOC - Break large files into smaller ones
3. Use generic renderers - Avoid hardcoded component TSX files
4. Store config in database - Use Prisma, not hardcoded values
5. Organize as packages - Self-contained features with seed data

For Pull Requests

For Pull Requests

1. Write descriptive PR titles - Used for automatic labeling
2. Link issues in PR descriptions - Enables automatic issue closing
3. Keep PRs focused and small - Easier to review and merge
4. Address all review comments - Even warnings should be considered
5. Test locally before pushing - Run lint and tests
6. Don't commit console.log statements - Will be flagged in review
7. Remove debugger statements - Treated as blocking issues
8. Review refactoring suggestions - Continuous improvement opportunities

For Issues

1. Use clear, descriptive titles - Helps with automatic categorization
2. Provide context - Link to docs/getting-started/PRD.md sections, mention permission levels
3. Consider architecture - Is this declarative? Package-worthy? Multi-tenant?
4. Use labels appropriately - Triggers relevant workflow automation
5. Engage with @copilot - Get AI assistance throughout implementation

Troubleshooting

Running Act to Find Workflow Issues

Use act to test workflows locally and identify issues before pushing:

# Run full diagnostics
./scripts/diagnose-workflows.sh

# Test specific failing job
act -j <job-name> -v

# Test entire CI pipeline
./scripts/test-workflows.sh

📖 Complete guide: ACT_TESTING.md

PR Not Auto-Merging

• Check that all CI checks passed
• Verify PR has approval
• Ensure no merge conflicts
• Confirm PR is not in draft mode

Tests Failing

• Run tests locally: bun run test:e2e
• Check test report artifacts in GitHub Actions
• Ensure dev server starts correctly
• Test with act: act -j test-e2e

Linting Errors

• Run bun run lint:fix to auto-fix
• Review errors: bun run lint
• Check eslint.config.js for rule configuration
• Test with act: act -j lint

Build Failures

• Test locally: bun run build
• Check for TypeScript errors
• Verify all dependencies are installed
• Test with act: act -j build

Prisma Issues

• Ensure schema exists: prisma/schema.prisma
• Generate client: bunx prisma generate
• Run migrations: bunx prisma migrate dev
• Test with act: act -j prisma-check

Contributing

When adding new workflows:

1. Document the workflow in this README
2. Add appropriate error handling
3. Test the workflow on a test branch
4. Ensure proper permissions are set
5. Add labels if needed (they'll be created automatically)

Security

Workflows use GITHUB_TOKEN with minimal required permissions:

• contents: read/write - For reading code and merging PRs
• pull-requests: write - For commenting and managing PRs
• issues: write - For managing issues
• checks: read - For reading CI status

No secrets are required for basic functionality.