GitHub Actions CI Workflow

Set up complete GitHub Actions workflows for continuous integration and deployment of worldbuilding applications.

Overview

To configure comprehensive CI/CD pipelines with GitHub Actions:

• Analyze the project structure and dependencies

• Generate workflow files for lint, test, build, and deploy stages

• Configure caching strategies for node_modules, Next.js cache, and build artifacts

• Add preview deployment with automatic URL comments on pull requests

• Set up environment-specific deployment targets

Workflow Structure

Create the following workflow files in .github/workflows/ :

CI Workflow (ci.yml )

To set up continuous integration:

• Configure triggers for push to main/master and pull requests

• Set up job matrix for multiple Node.js versions if needed

• Add checkout, dependency installation with caching

• Run linting (ESLint, Prettier, type checking)

• Execute test suites with coverage reporting

• Build the application to verify no build errors

• Upload build artifacts for deployment jobs

Deploy Workflow (deploy.yml )

To set up continuous deployment:

• Trigger on push to main/master branch

• Download build artifacts from CI workflow

• Deploy to target environment (Vercel, Netlify, AWS, etc.)

• Set environment variables and secrets

• Notify on deployment success/failure

Preview Deployment (preview.yml )

To set up preview deployments for pull requests:

• Trigger on pull_request events

• Build and deploy to preview environment

• Generate unique preview URL

• Comment preview URL on pull request using GitHub API

• Clean up preview deployments when PR is closed

Caching Strategy

To optimize workflow performance:

• Cache node_modules with dependency lock file as cache key

• Cache Next.js build cache (.next/cache ) for faster builds

• Cache testing artifacts and coverage reports

• Use actions/cache@v3 with appropriate cache keys

• Implement cache restoration fallbacks for partial matches

Resources

Consult references/github-actions-best-practices.md for workflow optimization patterns and security best practices.

Use scripts/generate_ci_workflow.py to scaffold workflow files based on detected project configuration.

Reference assets/workflow-templates/ for starter templates for common frameworks (Next.js, React, Node.js).

Implementation Steps

To implement complete CI/CD with GitHub Actions:

Detect Project Configuration

• Identify framework (Next.js, Vite, CRA, etc.)

• Detect package manager (npm, yarn, pnpm)

• Find test runner (Jest, Vitest, Playwright)

• Check for linting configuration

Generate Workflow Files

• Use scripts/generate_ci_workflow.py with detected configuration

• Customize jobs based on project requirements

• Add matrix builds if testing multiple environments

Configure Secrets and Variables

• Document required secrets in README or workflow comments

• Set up environment-specific variables

• Configure deployment credentials

Add Preview Deployments

• Generate preview workflow with URL commenting

• Configure preview environment provider

• Set up cleanup automation

Optimize Caching

• Implement multi-level caching strategy

• Use cache keys based on lock files

• Add cache restoration logic

Test and Validate

• Push workflows to repository

• Create test PR to verify preview deployments

• Check workflow execution times and optimize

Advanced Features

To add advanced CI/CD capabilities:

• Parallel Jobs: Split test suites across multiple jobs for faster execution

• Conditional Deployments: Deploy only specific paths or when conditions are met

• Status Checks: Require CI passing before merge

• Deployment Gates: Add manual approval steps for production deployments

• Performance Monitoring: Integrate Lighthouse CI or bundle analysis

• Dependency Updates: Automate dependency updates with Dependabot integration

Framework-Specific Configuration

Next.js Applications

To optimize for Next.js:

• Cache .next/cache directory for faster builds

• Set NEXT_TELEMETRY_DISABLED=1 to disable telemetry

• Use next build and next export for static exports

• Configure ISR revalidation for preview deployments

Full-Stack Applications

To handle full-stack deployments:

• Set up separate jobs for frontend and backend

• Configure database migrations in deployment workflow

• Run integration tests against preview environment

• Coordinate deployment order (backend first, then frontend)

Deployment Providers

Consult references/deployment-providers.md for platform-specific configuration:

• Vercel: Use vercel-action with project configuration

• Netlify: Use netlify-cli with site ID and auth token

• AWS: Configure S3/CloudFront or ECS deployment

• Docker: Build and push container images to registry

• Self-Hosted: SSH deployment with rsync or git pull

Monitoring and Notifications

To add monitoring and notifications:

• Configure Slack/Discord webhooks for deployment notifications

• Add GitHub status checks for required CI jobs

• Set up error tracking integration (Sentry, etc.)

• Monitor workflow execution times and optimize slow jobs

• Track deployment frequency and failure rates

Troubleshooting

Common issues and solutions:

• Cache Misses: Verify cache key includes all dependency files

• Timeout Errors: Increase timeout or split into parallel jobs

• Permission Errors: Check repository secrets and permissions

• Build Failures: Ensure environment variables are set correctly

• Preview URL Not Commented: Verify PR comment permissions and token scope