--- type: how-to title: Set Up CI/CD Workflows description: Configure GitHub Actions for automated
testing, quality checks, and deployment --- # Set Up CI/CD Workflows This guide shows you how to
configure and customize the included GitHub Actions workflows for your
{{projectName}}
project. ## Overview Your project includes two CI workflow options: - **Basic CI** (`ci.yml`) -
Ubuntu-only testing for simple projects - **Advanced CI** (`ci-advanced.yml`) - Cross-platform with
smart optimizations

{{#if IS_MONOREPO}}
  ## Monorepo Configuration Your project is configured as a monorepo with the following CI
  optimizations: - **Smart testing**: Only runs cross-platform tests for CLI code changes -
  **Parallel execution**: Tests packages independently with `--concurrency` - **Build
  dependencies**: Proper package build order with Turborepo - **Selective filtering**: Uses
  path-based filtering to reduce unnecessary runs

{{else}}
  ## Single Package Configuration Your project uses optimized CI for single-package development: -
  **Fast feedback**: Sequential quality checks with early failure detection - **Efficient caching**:
  Targeted caching for faster builds - **Simple workflow**: Focused on essential quality gates

{{/if}}

## Workflow Selection ### Basic CI (Recommended for most projects) ```yaml #
.github/workflows/ci.yml name: CI on: push: branches: [main, develop] pull_request: branches: [main,
develop] ``` **Features:** - Ubuntu-only testing (faster, lower cost) - Matrix quality checks (lint,
format, types) - Test execution with coverage - Security auditing
{{#if IS_MONOREPO}}- Build verification{{/if}}

**Best for:** - Web applications - Libraries without OS-specific code - Cost-conscious projects ###
Advanced CI (For cross-platform CLIs) ```yaml # .github/workflows/ci-advanced.yml name: CI -
Advanced on: push: branches: [main, develop] schedule: - cron: '0 8 * * 1' # Weekly regression
testing ``` **Features:** - **Smart cross-platform testing** - Only when needed - **56% cost
reduction** through intelligent filtering - **Path-based triggers** - Detects CLI vs other changes -
**Weekly scheduled testing** - Maintains quality with lower frequency - **Consolidated quality
checks** - Efficient matrix execution **Best for:** - CLI applications - Cross-platform libraries -
Projects requiring Windows/macOS compatibility ## Configuration ### Environment Variables Set these
in your GitHub repository settings: ```bash # Required for coverage reporting
CODECOV_TOKEN=your_codecov_token # Optional: Custom test configuration TEST_TIMEOUT=30000
{{#if IS_MONOREPO}}TURBO_TOKEN=your_turbo_token{{/if}}
``` ### Path Filtering (Advanced CI only) The advanced workflow automatically detects changes that
require cross-platform testing: ```yaml filters: | cli: - 'src/**'
{{#if IS_MONOREPO}}- 'packages/*/src/**'{{/if}}
workflows: - '.github/workflows/**' deps: - '{{#if
  (eq PACKAGE_MANAGER 'pnpm')
}}pnpm-lock.yaml{{else}}package-lock.json{{/if}}'
{{#if IS_MONOREPO}}- 'turbo.json'{{/if}}
``` **Triggers cross-platform testing when:** - Source code changes (`src/**`) - Workflow changes
(`.github/**`) - Dependency changes (lockfile,
{{#if IS_MONOREPO}}turbo.json{{/if}}) - Manual dispatch or scheduled run ### Caching Strategy Both
workflows use intelligent caching: ```yaml # Example cache configuration - name: Cache build
artifacts uses: actions/cache@v4 with: path: |
{{#if IS_MONOREPO}}.turbo{{else}}node_modules/.cache{{/if}}
coverage/ dist/ key: $\{{ runner.os }}-$\{{ matrix.task.name }}-$\{{ hashFiles('{{#if
  (eq PACKAGE_MANAGER 'pnpm')
}}pnpm-lock.yaml{{else}}package-lock.json{{/if}}') }} continue-on-error: true ``` **Cache
benefits:** - **40% faster builds** on cache hits - **Reduced CI minutes** usage - **Parallel job
efficiency** through shared artifacts ## Customization ### Adding Custom Quality Checks To add a new
quality check to the matrix: ```yaml # In ci.yml or ci-advanced.yml matrix: task: - name: lint
command:
{{PACKAGE_MANAGER}}
lint - name: format command:
{{PACKAGE_MANAGER}}
format:check - name: types command:
{{PACKAGE_MANAGER}}
types # Add your custom check here - name: custom-check command:
{{PACKAGE_MANAGER}}
run custom-script ``` ### Modifying Test Execution

{{#if IS_MONOREPO}}
  For monorepo projects, customize package filtering: ```yaml # Test specific packages - name: Run
  tests run:
  {{PACKAGE_MANAGER}}
  test --filter=./packages/core ```

{{else}}
  For single packages, adjust test configuration: ```yaml # Custom test options - name: Run tests
  run:
  {{PACKAGE_MANAGER}}
  test --coverage --reporter=verbose ```

{{/if}}

### Branch Protection Rules Configure these branch protection rules in GitHub: 1. **Require status
checks**: ✅ All CI jobs must pass 2. **Require up-to-date branches**: ✅ Must be current with base
branch 3. **Require signed commits**: ✅ (Recommended) 4. **Restrict pushes**: ✅ Require pull
requests ## Performance Optimization ### Expected Performance **Basic CI:** - **Setup time**: ~30
seconds - **Quality checks**: ~2-3 minutes - **Tests**: ~2-5 minutes - **Total runtime**: ~4-8
minutes **Advanced CI:** - **Ubuntu-only changes**: ~4-6 minutes - **Cross-platform changes**:
~12-18 minutes - **Cost reduction**: 56% vs. always running cross-platform ### Optimization Tips 1.
**Use Basic CI** unless you need cross-platform testing 2. **Enable caching** for all matrix jobs 3.
**Use path filtering** to skip unnecessary runs 4. **Run security audits** with `continue-on-error:
true` 5. **Schedule heavy tests** weekly instead of per-commit ## Troubleshooting ### Common Issues
**Cache misses:** ```bash # Check cache key consistency key: $\{{ runner.os }}-$\{{
hashFiles('pnpm-lock.yaml') }} ``` **Path filter not working:** ```yaml # Ensure paths are relative
to repository root filters: | cli: - 'src/**' # Correct - './src/**' # Incorrect ``` **Test
timeouts:** ```yaml # Increase timeout for long-running tests - name: Run tests run:
{{PACKAGE_MANAGER}}
test timeout-minutes: 15 ``` ### Performance Issues **Slow CI builds:** 1. Check cache hit rates in
workflow logs 2. Optimize test parallelization 3. Consider reducing test scope for PRs **High CI
costs:** 1. Use Advanced CI with path filtering 2. Enable weekly scheduled testing 3. Disable
unnecessary matrix combinations ## Security Considerations ### Secret Management Never commit
secrets to your repository. Use GitHub secrets: ```yaml env: SECRET_VALUE: $\{{ secrets.SECRET_NAME
}} ``` ### Dependency Security The workflows include automatic security auditing: ```yaml - name:
Run security audit run:
{{PACKAGE_MANAGER}}
audit continue-on-error: true # Don't fail CI on vulnerabilities ``` ## Next Steps 1. **Choose your
workflow**: Start with Basic CI, upgrade to Advanced if needed 2. **Configure secrets**: Add
required tokens for coverage and caching 3. **Set branch protection**: Enforce CI requirements 4.
**Monitor performance**: Check CI runtime and costs 5. **Customize as needed**: Add project-specific
quality checks For more advanced CI/CD patterns, see the [Advanced Deployment
Guide](./deploy-advanced.md).