metabuilder/docs/troubleshooting/testing/WORKFLOW_FAILURE_DIAGNOSIS.md

GitHub Workflows Failure Diagnosis

Date: December 24, 2024
Status: 🔍 Analysis Complete

Most Likely Causes of Workflow Failures

1. ❌ Prisma Migration Failing (High Probability)

Workflow: ci.yml - prisma-check job

Issue: The workflow tries to run prisma migrate deploy without a .env file or proper DATABASE_URL.

- name: Apply Prisma migrations
  run: npx prisma migrate deploy --schema prisma/schema.prisma
  env:
    DATABASE_URL: file:./dev.db

Problem:

• The DATABASE_URL is set to file:./dev.db but the database file doesn't exist in the CI environment
• prisma migrate deploy expects existing migrations to apply, but a fresh database needs prisma migrate dev or seeding
• No .env file exists in CI with proper configuration

Fix Needed:

1. Change migrate deploy to migrate dev for CI, OR
2. Add a setup step to create the database first, OR
3. Use in-memory database or test fixture

---

2. ❌ Missing Prisma Client Generation (High Probability)

Issue: The workflow generates Prisma client, but subsequent jobs (lint, build) don't regenerate it.

In ci.yml:

• prisma-check job generates the client
• lint and build jobs run npm ci which installs deps but doesn't regenerate Prisma client
• Code imports @prisma/client which may not exist

Fix Needed: Add npx prisma generate to each job that needs the Prisma client:

- name: Install dependencies
  run: npm ci

- name: Generate Prisma Client
  run: npx prisma generate

---

3. ⚠️ npm ci Failing Due to Package Lock Issues (Medium Probability)

Issue: Running npm ci may fail if:

• package-lock.json is out of sync with package.json
• Missing packages in npm registry
• Version conflicts

Evidence from npm list output:

npm error missing: @playwright/test@^1.57.0, required by spark-template@0.0.0
npm error missing: @prisma/client@^6.3.1, required by spark-template@0.0.0
npm error missing: prisma@^6.3.1, required by spark-template@0.0.0

Fix Needed:

1. Run npm install locally to regenerate package-lock.json
2. Commit updated lock file
3. OR use npm install instead of npm ci in workflows (slower but more forgiving)

---

4. ⚠️ Build Failing Due to TypeScript Errors (Medium Probability)

Workflow: ci.yml - build job

Issue: The build command uses tsc -b --noCheck:

"build": "tsc -b --noCheck && vite build"

Problem:

• --noCheck is not a valid TypeScript flag (should be --noEmit or --skipLibCheck)
• This causes tsc to fail immediately

Fix Needed: Change in package.json:

"build": "tsc -b && vite build"

OR

"build": "vite build"

---

5. ⚠️ ESLint Failing on Code Quality (Medium Probability)

Workflow: ci.yml - lint job

Likely Issues:

• Console.log statements in code
• TypeScript any types
• Unused variables
• Missing React dependencies

Fix Needed:

1. Run npm run lint locally to see errors
2. Run npm run lint:fix to auto-fix
3. Manually fix remaining issues

---

6. ⚠️ Playwright Tests Failing (Medium Probability)

Workflow: ci.yml - test-e2e job

Likely Issues:

• Database not seeded in test environment
• Default credentials don't exist
• App fails to start due to missing Prisma client
• Tests expect data that doesn't exist

Fix Needed:

1. Ensure database is properly seeded before tests
2. Add database setup step before Playwright tests
3. Mock or stub database calls in tests

---

7. ❌ Auto-Merge Workflow Incorrect Event Handling (Low Probability)

Workflow: auto-merge.yml

Issue: The workflow tries to extract PR number from workflow_run event, but the logic may fail if:

• No PRs exist for the branch
• Event payload structure is different

Not Blocking: This won't cause CI to fail, but auto-merge won't work.

---

8. ⚠️ Code Review Workflow JSON Parsing (Low Probability)

Workflow: code-review.yml

Issue: The workflow uses fromJSON() to parse step outputs:

if: steps.analyze.outputs.result && !fromJSON(steps.analyze.outputs.result).hasBlockingIssues

Potential Problem:

• If the output isn't valid JSON, this fails
• If the script errors, output is empty

Fix Needed: Add error handling in the github-script action

---

Priority Fix List

🚨 Critical (Must Fix for Workflows to Pass)

1. Fix Prisma setup in CI

   • Add Prisma client generation to all jobs
   • Fix database initialization
   • Use proper migration strategy

2. Fix package-lock.json

   • Regenerate with npm install
   • Commit changes

3. Fix build script

   • Remove invalid --noCheck flag
   • Use proper TypeScript build

⚠️ Important (Will Cause Failures)

4. Fix ESLint errors

   • Run npm run lint:fix
   • Fix remaining manual errors

5. Fix E2E tests

   • Ensure database seeding works in CI
   • Verify test credentials

📝 Nice to Have (Won't Block CI)

6. Improve auto-merge workflow

   • Add better error handling
   • Add more logging

7. Improve code review workflow

   • Add JSON validation
   • Add fallback for errors

---

How to Diagnose Locally

1. Check if Prisma works:

export DATABASE_URL="file:./dev.db"
npx prisma generate
npx prisma migrate dev

2. Check if build works:

npm run build

3. Check if lint works:

npm run lint

4. Check if tests work:

npm run test:e2e

5. Simulate CI locally:

# Clean install like CI does
rm -rf node_modules
npm ci
npx prisma generate
npm run lint
npm run build
npm run test:e2e

---

Using 'act' to Test Workflows Locally

The project includes scripts to test workflows locally using act:

# Run full CI pipeline
npm run act

# Run specific jobs
npm run act:lint
npm run act:e2e

# Run custom workflow
bash scripts/run-act.sh -w ci.yml -j build

Note: You need to install act first:

# macOS
brew install act

# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

---

Recommended Action Plan

Step 1: Fix Local Environment

# Regenerate lock file
npm install

# Generate Prisma client
npx prisma generate

# Try to build
npm run build

# Try to lint
npm run lint:fix
npm run lint

# Try tests
npm run test:e2e

Step 2: Update CI Workflow

Add Prisma generation to each job in .github/workflows/ci.yml:

- name: Install dependencies
  run: npm ci

- name: Generate Prisma Client
  run: npx prisma generate
  env:
    DATABASE_URL: file:./dev.db

Step 3: Fix package.json Build Script

"build": "tsc && vite build"

Step 4: Commit and Push

git add package-lock.json package.json .github/workflows/ci.yml
git commit -m "Fix CI workflow issues"
git push

Step 5: Monitor Workflow

Check GitHub Actions tab to see if workflows pass.

If you're inside the app, the GitHub Actions Monitor (Level 1) can fetch run logs, download them locally, and surface common error signals. For private repos or higher rate limits, set GITHUB_TOKEN. To target a different repository, set GITHUB_OWNER and GITHUB_REPO (used by the /api/github/actions/runs and /api/github/actions/runs/{runId}/logs endpoints). The logs endpoint also accepts jobLimit and includeLogs query parameters.

---

Summary

Most Likely Root Causes:

1. ✅ Prisma client not generated in CI jobs
2. ✅ Database not properly initialized
3. ✅ Invalid TypeScript build flag (--noCheck)
4. ✅ Package lock file issues

Quick Test:

rm -rf node_modules dist
npm ci
npx prisma generate
npm run build
npm run lint

If the above succeeds locally, the workflows should pass after adding Prisma generation to CI jobs.