GitHub Actions CI/CD

Comprehensive guide to the GitHub Actions workflows for continuous integration and deployment.

Overview

The template includes two main GitHub Actions workflows:

1. CI Pipeline (ci.yml) - Quality gates and testing
2. Documentation Deployment (deploy-docs.yml) - VitePress to GitHub Pages

CI Pipeline (.github/workflows/ci.yml)

Triggers

• Push to main branch
• Pull requests to main branch

Jobs

Quality Gates

- name: Run quality checks
  run: npm run check

- name: Build project  
  run: npm run build

- name: Generate API documentation
  run: npm run docs:api

- name: Build documentation
  run: npm run docs:build

Multi-Version Testing

• Node.js 18 (LTS)
• Node.js 20 (Current)

Security Auditing

- name: Audit dependencies
  run: npm audit --audit-level=moderate

Quality Standards

• ✅ All ESLint rules pass
• ✅ Prettier formatting enforced
• ✅ 80%+ test coverage required
• ✅ TypeScript compilation succeeds
• ✅ Documentation builds successfully

Documentation Deployment (.github/workflows/deploy-docs.yml)

Triggers

• Push to main branch (deploys)
• Pull requests to main branch (builds only)

Deployment Process

1. Generate API docs with TypeDoc
2. Build VitePress documentation
3. Deploy to GitHub Pages automatically

Configuration

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

Setup Instructions

1. Enable GitHub Pages

1. Go to repository Settings → Pages
2. Set source to GitHub Actions
3. Save configuration

2. Configure Secrets (if needed)

For private repositories or additional integrations:

# Example secrets (not required for basic setup)
NPM_TOKEN=your_npm_token
CODECOV_TOKEN=your_codecov_token

3. Branch Protection

Recommended branch protection rules for main:

• ✅ Require status checks to pass
• ✅ Require branches to be up to date
• ✅ Include administrators
• ✅ Restrict pushes that create files

Workflow Customization

Adding New Quality Gates

- name: Custom quality check
  run: npm run custom:check

- name: Security scan
  run: npm run security:scan

Environment-Specific Builds

strategy:
  matrix:
    node-version: [18, 20]
    environment: [development, production]

Conditional Steps

- name: Deploy to staging
  if: github.ref == 'refs/heads/develop'
  run: npm run deploy:staging

- name: Deploy to production  
  if: github.ref == 'refs/heads/main'
  run: npm run deploy:production

Monitoring and Debugging

Workflow Status

• Green checkmark: All checks passed
• Red X: One or more checks failed
• Yellow circle: Checks in progress

Debugging Failed Builds

1. Click on failed workflow in Actions tab
2. Expand failed step to see error details
3. Check logs for specific error messages
4. Re-run jobs if needed

Common Issues

Node.js Version Mismatch

# Ensure consistent Node.js version
- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: 20

Cache Issues

# Clear cache if needed
- name: Clear npm cache
  run: npm cache clean --force

Permission Issues

# Ensure proper permissions
permissions:
  contents: read
  pages: write
  id-token: write

Performance Optimization

Caching Dependencies

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: npm

Parallel Jobs

jobs:
  test:
    # Test job
  build:
    # Build job  
  deploy:
    needs: [test, build]
    # Deploy only after test and build succeed

Conditional Execution

- name: Skip on draft PRs
  if: github.event.pull_request.draft == false
  run: npm run expensive:check

Security Best Practices

Dependency Auditing

- name: Audit dependencies
  run: npm audit --audit-level=moderate

- name: Check for vulnerabilities
  run: npm run security:check

Secret Management

• ✅ Use GitHub Secrets for sensitive data
• ✅ Limit secret access to necessary workflows
• ✅ Rotate secrets regularly
• ✅ Use least-privilege principle

Code Scanning

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    languages: typescript

- name: Perform CodeQL Analysis
  uses: github/codeql-action/analyze@v2

Integration Examples

Slack Notifications

- name: Notify Slack
  if: failure()
  uses: 8398a7/action-slack@v3
  with:
    status: failure
    webhook_url: ${{ secrets.SLACK_WEBHOOK }}

Code Coverage

- name: Upload coverage
  uses: codecov/codecov-action@v3
  with:
    file: ./coverage/lcov.info

Deployment Status

- name: Update deployment status
  uses: bobheadxi/deployments@v1
  with:
    step: finish
    token: ${{ secrets.GITHUB_TOKEN }}
    status: success
    deployment_id: ${{ steps.deployment.outputs.deployment_id }}

Troubleshooting Guide

Build Failures

1. Check Node.js version compatibility
2. Verify dependencies are correctly installed
3. Review error logs for specific issues
4. Test locally with same Node.js version

Deployment Issues

1. Verify GitHub Pages is enabled
2. Check permissions are correctly set
3. Ensure base URL matches repository name
4. Review deployment logs for errors

Performance Issues

1. Enable caching for dependencies
2. Use matrix builds for parallel execution
3. Optimize test suites for faster execution
4. Consider workflow triggers to reduce unnecessary runs