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.tx