Continuous Integration

Purpose and Scope

This document describes the continuous integration (CI) workflow that validates code quality for the simap-mcp server on every push and pull request. The CI workflow executes a series of quality gates including linting, type checking, formatting validation, compilation, and unit testing across a matrix of Node.js versions.

As of version 1.3.0, the project requires Node.js >=22. Consequently, the CI matrix has been updated to test against Node.js versions 22 and 24, dropping support for Node.js 20 which reached end-of-life on 2026-04-30.

Additionally, as of version 1.2.3, the CI workflow incorporates hardened security permissions, implementing a least-privilege model for the GITHUB_TOKEN to resolve potential CodeQL and workflow permission issues.

Workflow Overview

The CI workflow is defined in .github/workflows/ci.yml and implements a comprehensive quality gate system. The workflow runs automatically on every push to the main branch and on all pull requests targeting main.

Workflow Trigger and Security Configuration

Sources: .github/workflows/ci.yml1-10 .github/workflows/ci.yml13-18

The workflow uses GitHub Actions' on event triggers to respond to code changes. Lines 4-5 configure push events on the main branch, while lines 6-7 configure pull request events targeting main.

Security and Permissions

To follow security best practices and resolve "missing-workflow-permissions" warnings in security scans, the workflow explicitly defines its permission scope at the top level. By setting permissions: contents: read at .github/workflows/ci.yml9-10 the GITHUB_TOKEN is restricted to read-only access to the repository contents, preventing accidental write operations by the CI job or third-party actions.

Node.js Version Matrix

The CI workflow validates code across the current supported Node.js versions. The matrix strategy executes all quality gates independently on Node.js versions 22 and 24. Node.js 20 was removed from the matrix in v1.3.0 as it reached end-of-life.

Matrix Build Strategy

Configuration	Value
Runner OS	ubuntu-latest
Node.js Versions	22, 24
Cache Strategy	npm

Sources: .github/workflows/ci.yml14-27

The matrix configuration is defined at .github/workflows/ci.yml16-18 using GitHub Actions' strategy.matrix feature. Each version in the matrix spawns an independent job execution. The node-version variable is interpolated in the setup step at .github/workflows/ci.yml23-26

Quality Gate Pipeline

The CI workflow implements sequential quality gates that must all pass for the build to succeed. Each gate validates a different aspect of code quality, from syntax to runtime behavior.

CI Quality Gates Flow

Sources: .github/workflows/ci.yml21-45

Step 1: Repository Checkout

The workflow begins by cloning the repository using actions/checkout@v6 at .github/workflows/ci.yml21

Step 2: Node.js Environment Setup

The actions/setup-node@v6 action configures the Node.js runtime and npm package cache at .github/workflows/ci.yml23-27

Step 3: Dependency Installation

The npm ci command executes at .github/workflows/ci.yml30 This provides a clean, reproducible dependency installation based on package-lock.json.

Step 4: Linting

The linting gate executes at .github/workflows/ci.yml32-33 by running npm run lint. This ensures the code adheres to the project's stylistic and programmatic rules.

Step 5: Type Checking

The type checking gate executes at .github/workflows/ci.yml35-36 by running npm run typecheck. This invokes tsc --noEmit to perform TypeScript type validation without generating output files, ensuring the integrity of internal interfaces and Zod schemas.

Step 6: Format Checking

The formatting gate executes at .github/workflows/ci.yml38-39 by running npm run format:check. This script invokes prettier --check to validate that all source files conform to the project's formatting rules.

Step 7: Build

The build gate executes at .github/workflows/ci.yml41-42 by running npm run build. This compiles TypeScript source files into the dist/ directory, verifying that the project can be successfully transpiled for distribution.

Step 8: Test

The final quality gate executes at .github/workflows/ci.yml44-45 by running npm test. This script invokes the vitest test runner to execute the full suite of unit and integration tests.

Code Review Integration

The project utilizes CodeRabbit for automated AI-driven code reviews. This is configured in .coderabbit.yaml to provide feedback on pull requests.

CodeRabbit Configuration

Feature	Setting
Auto Review	Enabled .coderabbit.yaml3
Ignored Users	dependabot[bot], github-actions[bot] .coderabbit.yaml7-8
Ignored Titles	"Version Packages" (Changeset PRs) .coderabbit.yaml5

Sources: .coderabbit.yaml1-9

CI and Development Workflow Integration

The CI workflow provides automated feedback that developers can replicate locally using the scripts defined in the project's configuration.

Local Validation Commands

Command	CI Step Reference
npm run lint	Linting at .github/workflows/ci.yml32-33
npm run typecheck	Type Checking at .github/workflows/ci.yml35-36
npm run format:check	Format Checking at .github/workflows/ci.yml38-39
npm run build	Build at .github/workflows/ci.yml41-42
npm test	Test at .github/workflows/ci.yml44-45

The matrix strategy ensures that code changes work correctly across the entire supported Node.js range (22, 24). All quality gates must pass on both Node.js versions for the CI workflow to be considered successful.