metabuilder/.github/workflows/README.md

# 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](../../docs/ENTERPRISE_GATED_WORKFLOW.md)

### 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](../../docs/LEGACY_PIPELINE_CRUFT_REPORT.md) 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](../copilot-instructions.md)

## Workflows Overview

### 🚦 Enterprise Gated Workflows (New)

#### Issue and PR Triage (`triage.yml`) 🆕
**Triggered on:** Issues (opened/edited/reopened) and Pull Requests (opened/reopened/synchronize/edited)

**Purpose:** Quickly categorize inbound work so reviewers know what to look at first.

- Auto-applies labels for type (bug/enhancement/docs/security/testing/performance) and area (frontend/backend/database/workflows/documentation)
- Sets a default priority and highlights beginner-friendly issues
- Flags missing information (repro steps, expected/actual results, versions) with a checklist comment
- For PRs, labels areas touched, estimates risk based on change size and critical paths, and prompts for test plans/screenshots/linked issues
- Mentions **@copilot** to sanity-check the triage with GitHub-native AI (no external Codex webhooks)

This workflow runs alongside the existing PR management jobs to keep triage lightweight while preserving the richer checks in the gated pipelines.

#### 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](../../docs/ATOMIC_GATED_WORKFLOW.md)

#### 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:**
```markdown
@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](https://github.com/nektos/act):

```bash
# 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](../../docs/ACT_TESTING.md) for comprehensive act testing guide**

### Running Locally

```bash
# 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:

```bash
# 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](../../docs/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.