CI_CD.md•6.08 kB
# Continuous Integration (CI/CD)
This document describes the automated CI/CD pipeline for the MCP Cut-Copy-Paste Clipboard Server.
## Overview
The project uses **GitHub Actions** for continuous integration to ensure code quality on every push and pull request.
## CI Pipeline
### Workflow File
Location: `.github/workflows/ci.yml`
### Triggers
The CI pipeline runs on:
- **Push to `main` branch**: Validates all changes before they're merged
- **Pull Requests to `main`**: Ensures PRs meet quality standards before review
### Test Matrix
Tests run on multiple Node.js versions to ensure compatibility:
- **Node.js 18.x** (minimum supported version)
- **Node.js 20.x** (LTS version)
- **Node.js 22.x** (latest stable)
## Pipeline Steps
### 1. Checkout Code
```yaml
- uses: actions/checkout@v4
```
Retrieves the repository code for testing.
### 2. Setup Node.js
```yaml
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
```
Installs the specified Node.js version and caches npm dependencies for faster builds.
### 3. Install Dependencies
```bash
npm ci
```
Performs a clean install of all dependencies using `package-lock.json` for reproducibility.
### 4. Run Linter
```bash
npm run lint
```
Checks TypeScript code for:
- Code quality issues
- Style violations
- Potential bugs
- TypeScript strict mode compliance
**Fails if**: ESLint finds any errors.
### 5. Check Formatting
```bash
npm run format:check
```
Verifies code formatting using Prettier.
**Fails if**: Any file doesn't match Prettier rules.
### 6. Build TypeScript
```bash
npm run build
```
Compiles TypeScript to JavaScript.
**Fails if**: TypeScript compilation errors occur.
### 7. Run Tests
```bash
npm test
```
Executes the full test suite (161 tests across 11 test suites).
**Fails if**: Any test fails.
### 8. Generate Coverage Report
```bash
npm run test:coverage
```
Generates test coverage report (only on Node.js 20.x to avoid redundancy).
**Coverage Thresholds**:
- Statements: ≥85%
- Lines: ≥85%
- Functions: ≥95%
- Branches: ≥70%
**Note**: Entry points (`cli.ts`, `server.ts`) are excluded from coverage as they're integration-tested. Core business logic maintains 90%+ coverage.
### 9. Upload Coverage to Codecov
```yaml
- uses: codecov/codecov-action@v3
with:
files: ./coverage/lcov.info
```
Uploads coverage report to Codecov (optional, doesn't fail CI).
## CI Status Badge
The README displays a CI status badge:
```markdown
[](https://github.com/Pr0j3c7t0dd-Ltd/cut-copy-paste-mcp/actions/workflows/ci.yml)
```
This badge shows:
- ✅ Green "passing" when all checks succeed
- ❌ Red "failing" when any check fails
## Local Testing
Before pushing, you can run the same checks locally:
```bash
# Run all CI checks locally
npm run lint # ESLint
npm run format:check # Prettier
npm run build # TypeScript compilation
npm test # Test suite
npm run test:coverage # Coverage report
```
Or run them all in sequence:
```bash
npm run lint && npm run format:check && npm run build && npm test
```
## Quality Gates
For a commit/PR to pass CI, **all** of the following must succeed:
| Check | Requirement |
|-------|-------------|
| ✅ **Linting** | No ESLint errors |
| ✅ **Formatting** | All files match Prettier rules |
| ✅ **Build** | TypeScript compiles without errors |
| ✅ **Tests** | All 161 tests pass |
| ✅ **Coverage** | Statements/Lines ≥85%, Functions ≥95%, Branches ≥70% |
| ✅ **Node Compatibility** | Works on Node 18.x, 20.x, 22.x |
## Failure Scenarios
### Linting Failure
```
Error: src/example.ts:10:5 - error TS2322: Type 'string' is not assignable to type 'number'
```
**Solution**: Fix TypeScript/ESLint errors in your code.
### Formatting Failure
```
[warn] src/example.ts
[warn] Code style issues found in the above file(s). Forgot to run Prettier?
```
**Solution**: Run `npm run format` to auto-fix formatting.
### Test Failure
```
FAIL src/__tests__/example.test.ts
● Test Suite › should pass
expect(received).toBe(expected)
```
**Solution**: Fix the failing test or the code it's testing.
### Coverage Failure
```
Jest: "global" coverage threshold for statements (85%) not met: 82%
```
**Solution**: Add more tests to increase coverage. Note that entry points (`cli.ts`, `server.ts`) are excluded from coverage requirements.
## Performance
Typical CI run time:
- **Single Node version**: ~30-40 seconds
- **All 3 Node versions**: ~90-120 seconds (parallel execution)
Caching optimizations:
- npm dependencies cached between runs (~20s faster)
- Node.js installation cached
## Future Enhancements
Planned additions to CI/CD:
1. **Automated Publishing**: Publish to npm on version tags
2. **Release Automation**: Generate release notes from commits
3. **Security Scanning**: Add dependency vulnerability checks
4. **Performance Testing**: Add benchmarks to CI
5. **Docker Builds**: Test Docker container builds
## Troubleshooting
### CI Passes Locally But Fails on GitHub
**Common Causes**:
1. Different Node.js versions
2. Platform-specific issues (macOS vs Linux)
3. Uncommitted package-lock.json changes
4. Environment variables not set
**Solution**: Check the specific Node.js version that failed and test locally with that version.
### Flaky Tests
If tests occasionally fail in CI:
1. Check for race conditions
2. Look for non-deterministic behavior
3. Review test timeouts
4. Check for reliance on system state
## Contributing
When submitting a PR:
1. ✅ Ensure all CI checks pass locally first
2. ✅ Write tests for new features
3. ✅ Update documentation
4. ✅ Follow code style (run `npm run format`)
5. ✅ Maintain coverage thresholds (≥85% statements/lines, ≥95% functions, ≥70% branches)
The CI pipeline will automatically verify these requirements.
---
**Questions?** Check the [GitHub Actions documentation](https://docs.github.com/en/actions) or open an issue.