GitHub Actions CI/CD Documentation

This repository uses GitHub Actions for automated CI/CD with comprehensive quality gates, automated releases, and dependency management.

Table of Contents

• Overview
• Workflows
• Setup Instructions
• Status Checks
• Release Process
• Secrets and Variables
• Troubleshooting

Overview

Our CI/CD pipeline includes:

• Continuous Integration: Automated testing, linting, and quality checks on every PR
• Quality Gates: Bundle size tracking, security audits, license compliance
• Automated Releases: Semantic versioning and npm publishing
• Dependency Management: Automated dependency updates via Dependabot

Workflows

1. CI Workflow (.github/workflows/ci.yml)

Triggers: Pull requests and pushes to master

Jobs:

lint-and-format

• Runs ESLint on TypeScript files
• Checks Prettier formatting
• Validates package.json
• Runtime: ~2-3 minutes
• Node Version: 20

build

• Compiles TypeScript to JavaScript
• Verifies build artifacts (dist/)
• Uploads build artifacts for use in other jobs
• Runtime: ~2-3 minutes
• Node Version: 20

test

• Runs unit tests across multiple Node versions (18, 20, 22)
• Generates code coverage reports
• Uploads coverage to Codecov
• Enforces 80% coverage threshold
• Runtime: ~5-8 minutes per Node version
• Matrix Strategy: Parallel execution across Node versions

performance-benchmarks

• Runs performance benchmark suite
• Compares results against baseline
• Fails if performance regression >10%
• Posts results as PR comment
• Runtime: ~3-5 minutes
• Node Version: 20

integration-test

• Starts MCP server
• Runs integration tests against live server
• Uploads logs on failure
• Runtime: ~3-5 minutes
• Node Version: 20
• Depends On: build job

status-check

• Aggregates all job results
• Final gate before PR can be merged
• Runtime: <1 minute
• Depends On: All other jobs

Total CI Runtime: ~10-15 minutes (with parallelization)

2. Release Workflow (.github/workflows/release.yml)

Triggers: Push to master (after PR merge)

Jobs:

release

• Analyzes commits using conventional commit format
• Determines version bump (major/minor/patch)
• Generates CHANGELOG.md
• Creates Git tag
• Creates GitHub Release
• Runtime: ~3-5 minutes
• Node Version: 20

publish

• Publishes package to npm
• Verifies publication
• Only runs if new release was created
• Runtime: ~2-3 minutes
• Node Version: 20
• Depends On: release job

notify

• Posts release announcement (Discord/Slack if configured)
• Comments on related issues
• Updates release summary
• Runtime: ~1-2 minutes
• Depends On: release, publish jobs

Total Release Runtime: ~6-10 minutes

3. Quality Gates Workflow (.github/workflows/quality-gates.yml)

Triggers: Pull requests and pushes to master

Jobs:

bundle-size

• Analyzes compiled bundle size
• Compares against baseline
• Fails if size increases >5%
• Posts size comparison as PR comment
• Runtime: ~2-3 minutes

security-audit

• Runs npm audit
• Fails on critical vulnerabilities
• Warns on high vulnerabilities
• Posts audit results as PR comment
• Runtime: ~2-3 minutes

license-compliance

• Checks all dependency licenses
• Warns about copyleft licenses (GPL, AGPL, LGPL)
• Generates license report
• Runtime: ~2-3 minutes

dependency-vulnerabilities

• Runs Snyk scan (if configured)
• Checks for outdated dependencies
• Generates vulnerability report
• Runtime: ~2-3 minutes

code-quality

• Analyzes code complexity
• Counts lines of code
• Identifies TODO/FIXME comments
• Runtime: ~1-2 minutes

Total Quality Gates Runtime: ~9-14 minutes (parallel execution)

4. Commit Lint Workflow (.github/workflows/commitlint.yml)

Triggers: Pull requests

Jobs:

commitlint

• Validates all PR commits follow Conventional Commits format
• Posts format guide as PR comment on failure
• Runtime: ~1-2 minutes

5. Dependabot Configuration (.github/dependabot.yml)

Schedule: Weekly (Monday 9:00 AM UTC)

Features:

• Groups minor/patch updates for dev dependencies
• Groups patch updates for production dependencies
• Separate PRs for major version updates
• Auto-assigns to @ooples
• Labels: dependencies, automated

Setup Instructions

1. Initial Setup

1. Clone the repository

   git clone https://github.com/ooples/token-optimizer-mcp.git
   cd token-optimizer-mcp
   

2. Install dependencies

   npm install
   

3. Install semantic-release and commitlint globally (optional)

   npm install -g semantic-release @commitlint/cli
   

2. Configure GitHub Secrets

Navigate to: Settings > Secrets and variables > Actions > New repository secret

Add the following secrets:

Required Secrets

Secret Name	Description	How to Get
NPM_TOKEN	npm authentication token	https://www.npmjs.com/settings/YOUR_USERNAME/tokens
CODECOV_TOKEN	Codecov upload token (optional)	https://codecov.io/

Optional Secrets

Secret Name	Description	Use Case
SNYK_TOKEN	Snyk authentication token	Advanced security scanning

3. Configure GitHub Variables (Optional)

Navigate to: Settings > Secrets and variables > Actions > Variables tab

Variable Name	Description	Example
DISCORD_WEBHOOK_URL	Discord webhook for release notifications	https://discord.com/api/webhooks/...
SLACK_WEBHOOK_URL	Slack webhook for release notifications	https://hooks.slack.com/services/...

4. Set Up Branch Protection

Follow instructions in BRANCH_PROTECTION.md

5. Initialize Performance Baseline

After first successful CI run:

1. Download the benchmark results artifact
2. Copy to .github/performance-baseline.json
3. Commit and push:

   git add .github/performance-baseline.json
   git commit -m "chore: add performance baseline"
   git push
   

6. Initialize Bundle Size Baseline

After first successful build:

1. Run: du -sb dist | cut -f1 > .github/bundle-size-baseline.txt
2. Commit and push:

   git add .github/bundle-size-baseline.txt
   git commit -m "chore: add bundle size baseline"
   git push
   

Status Checks

All PRs must pass the following status checks before merging:

Critical Checks (Must Pass)

• ✅ lint-and-format - Code style and linting
• ✅ build - TypeScript compilation
• ✅ test (18) - Tests on Node 18
• ✅ test (20) - Tests on Node 20
• ✅ test (22) - Tests on Node 22
• ✅ commitlint - Commit message format

Quality Checks (Must Pass)

• ✅ bundle-size - Bundle size within limits
• ✅ security-audit - No critical vulnerabilities
• ✅ license-compliance - License compatibility

Optional Checks (Can Warn)

• ⚠️ performance-benchmarks - Performance metrics
• ⚠️ integration-test - Integration test suite
• ⚠️ code-quality - Code metrics and analysis

Release Process

Automated Release Flow

1. Developer creates PR with conventional commits

   • Format: type(scope): description
   • Examples: feat(auth): add OAuth, fix(api): resolve race condition

2. CI runs on PR

   • All status checks must pass
   • Code review required
   • Conversations must be resolved

3. PR is merged to master

   • Release workflow triggers automatically
   • Semantic-release analyzes commits

4. Version determination

   • fix: commits → Patch version (0.0.X)
   • feat: commits → Minor version (0.X.0)
   • BREAKING CHANGE: → Major version (X.0.0)

5. Automatic actions

   • CHANGELOG.md updated
   • Version bumped in package.json
   • Git tag created (e.g., v0.2.1)
   • GitHub Release created
   • npm package published
   • Related issues commented

Manual Release (Emergency)

If automated release fails:

# Ensure you're on master with latest changes
git checkout master
git pull

# Create version and tag
npm version patch -m "chore(release): %s"  # or minor/major

# Push changes and tags
git push && git push --tags

# Publish to npm
npm publish

# Create GitHub release manually
gh release create v0.2.1 --generate-notes

Secrets and Variables

Getting NPM Token

1. Log in to npm: https://www.npmjs.com/
2. Click your profile → "Access Tokens"
3. Click "Generate New Token" → "Classic Token"
4. Select "Automation" type
5. Copy token and add to GitHub Secrets as NPM_TOKEN

Getting Codecov Token (Optional)

1. Visit https://codecov.io/
2. Sign in with GitHub
3. Add your repository
4. Copy the upload token
5. Add to GitHub Secrets as CODECOV_TOKEN

Setting Up Notifications

Discord

1. Go to your Discord server settings
2. Navigate to "Integrations" → "Webhooks"
3. Create a new webhook
4. Copy the webhook URL
5. Add to GitHub Variables as DISCORD_WEBHOOK_URL

Slack

1. Go to https://api.slack.com/apps
2. Create a new app or select existing
3. Enable "Incoming Webhooks"
4. Add webhook to workspace
5. Copy the webhook URL
6. Add to GitHub Variables as SLACK_WEBHOOK_URL

Troubleshooting

CI Fails: "Coverage threshold not met"

Solution: Add more unit tests to reach 80% coverage

npm run test:coverage
# Check coverage/index.html for uncovered lines

CI Fails: "Bundle size increased by >5%"

Solution: Optimize bundle or update baseline

# Check what's causing size increase
npm run build
du -h dist/

# If increase is justified, update baseline:
du -sb dist | cut -f1 > .github/bundle-size-baseline.txt
git add .github/bundle-size-baseline.txt
git commit -m "chore: update bundle size baseline"

Release Fails: "No release published"

Cause: No conventional commits since last release

Solution: Ensure commits follow format:

• feat: for features
• fix: for bug fixes
• BREAKING CHANGE: for breaking changes

NPM Publish Fails: "Authentication failed"

Solution: Verify NPM_TOKEN secret

1. Check token is still valid: https://www.npmjs.com/settings/YOUR_USERNAME/tokens
2. Regenerate token if needed
3. Update GitHub secret

Dependabot PRs Failing

Solution: Review and fix issues

# Checkout Dependabot branch
git fetch origin
git checkout dependabot/npm_and_yarn/...

# Fix any breaking changes
npm install
npm test

# Commit fixes
git commit -am "fix: resolve dependency conflicts"
git push

Performance Benchmarks Failing

Solution: Investigate performance regression

1. Download benchmark artifacts from failed run
2. Compare with baseline
3. Profile the code to find bottleneck
4. Optimize or update baseline if acceptable

Best Practices

Commit Messages

✅ Good

feat(api): add token refresh endpoint
fix(cache): resolve memory leak in LRU cache
docs(readme): update installation instructions
refactor(core): simplify optimization logic

❌ Bad

Update code
Fix bug
WIP
changes

PR Workflow

1. Create feature branch: git checkout -b feat/my-feature
2. Make changes with conventional commits
3. Push and create PR
4. Wait for all checks to pass
5. Get code review approval
6. Squash and merge (if needed)

Testing Strategy

• Write unit tests for all new features
• Maintain 80%+ coverage
• Add integration tests for critical flows
• Update benchmarks for performance-sensitive code

Dependency Updates

• Review Dependabot PRs weekly
• Test major version updates thoroughly
• Group minor/patch updates when possible
• Keep dependencies up to date for security

Related Documentation

• Branch Protection Rules
• Conventional Commits
• Semantic Release
• GitHub Actions

Support

For issues with CI/CD:

1. Check GitHub Actions logs
2. Review this documentation
3. Open an issue: https://github.com/ooples/token-optimizer-mcp/issues