Skip to main content

troubleshooting

Troubleshooting

CI/CD Issues

Shell Syntax Error in sync:auto Job

Problem: Pipeline fails with syntax error: unterminated quoted string

Cause: Alpine Linux uses ash (not bash). Quotes inside JSON strings in heredocs break parsing.

Bad:

"description": "...\n/label ~\"workflow::auto-merge\" ~\"type::maintenance\"",

Good:

"description": "...\\n/label ~workflow::auto-merge ~type::maintenance",

Solution:

  1. Remove quotes around GitLab label names (they're optional)
  2. Escape newlines with \\n not \n in JSON
  3. Fixed in MR #264

pnpm vs npm Mismatch

Problem: CI job fails because pnpm-lock.yaml doesn't exist

Cause: Project uses npm but some CI jobs were configured for pnpm

Solution: Use npm commands:

# Bad
pnpm install --frozen-lockfile

# Good
npm ci --prefer-offline --no-audit || npm install

Review Environments Stuck in "Stopping" State

Problem: 24+ review environments stuck, cannot be deleted via API (403 Forbidden)

Cause: GitLab has restrictions on environment deletion in certain states

Solution: Manual cleanup via GitLab UI:

  1. Go to: Settings CI/CD Environments
  2. Or: https://gitlab.com/blueflyio/ossa/openstandardagents.org/-/environments/folders/review
  3. Click the trash icon for each stuck environment

Build Issues

Examples Page Shows Empty

Problem: /examples/ page loads but shows no examples

Cause: website/public/examples.json is empty []

Solution:

  1. Run npm run fetch-examples in website/ directory
  2. Or trigger the sync:auto CI job
  3. The scheduled pipeline runs every 6 hours automatically

TypeScript Build Errors

Problem: Build fails with TypeScript errors

Solution:

cd website
npm run typecheck  # Check for errors
npm run build      # Full build

Common fixes:

  • Check for missing type definitions
  • Verify all imports are correct
  • Run npm install to ensure dependencies are current

Development Issues

Local Development Not Loading Data

Problem: Site runs locally but pages are empty

Solution: Fetch all content sources:

cd website
npm run fetch-spec       # Fetch OSSA schema
npm run fetch-examples   # Fetch examples
npm run fetch-versions   # Fetch version info
npm run fetch-highlights # Fetch release highlights
npm run sync-version     # Sync version references
npm run fix-versions     # Fix any version mismatches

Git Push Rejected - Protected Branch

Problem: git push rejected because branch is protected

Cause: main and release/* branches require merge requests

Solution:

  1. Create feature branch: git checkout -b feature/my-change
  2. Push feature branch: git push -u origin feature/my-change
  3. Create MR in GitLab UI
  4. MR targets release/v0.3.x (not main directly)

Deployment Issues

Review App Not Deploying

Problem: Review app job runs but site not accessible

Cause: Requires local Kubernetes cluster (OrbStack) with KUBECONFIG_LOCAL CI variable

Solution:

  1. Set up OrbStack with K8s enabled
  2. Export kubeconfig: kubectl config view --raw | base64 | pbcopy
  3. Add KUBECONFIG_LOCAL as CI/CD variable (masked)
  4. Review apps deploy to *.openstandardagents.orb.local

GitLab Pages 404

Problem: GitLab Pages returns 404 after deployment

Cause: Build artifacts not in public/ directory

Solution:

  1. Verify pages job copies build to public/: 
    script:
  - cp -r website-build public
  2. Check artifacts path is public/
  3. Wait 5-10 minutes for Pages propagation

Performance Issues

Slow Build Times

Problem: CI pipeline takes too long

Solutions:

  1. Enable caching: 
    cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - website/node_modules/
    - website/.next/cache/
  2. Use npm ci instead of npm install
  3. Skip unnecessary jobs with rules

Getting Help

If you encounter issues not listed here:

  1. Check existing GitLab issues: https://gitlab.com/blueflyio/ossa/openstandardagents.org/-/issues
  2. Check CI/CD job logs for specific error messages
  3. Open a new issue with:
    • Error message
    • Steps to reproduce
    • Expected vs actual behavior