Version: 2.4.0 Last Updated: February 2026
- Overview
- GitHub Actions Workflows
- CI Workflow (Automated Testing)
- Lint Workflow (Code Quality)
- ESLint Configuration
- Prettier Configuration
- Local Pre-Commit Testing
- Troubleshooting CI Failures
- Badge Integration
- Best Practices
The KNII Ticketing System uses GitHub Actions for continuous integration and continuous deployment (CI/CD). This automation ensures code quality, prevents regressions, and maintains consistent coding standards across the project.
Key Benefits:
- ✅ Automated testing on every push and pull request
- ✅ Code quality enforcement (ESLint + Prettier)
- ✅ Security vulnerability scanning (npm audit)
- ✅ Test coverage tracking
- ✅ Docker-based test execution matching local dev workflow
Workflows:
- CI Workflow (
.github/workflows/ci.yml) - Runs tests, generates coverage - Lint Workflow (
.github/workflows/lint.yml) - Enforces code quality and formatting
Both workflows run automatically on:
- Push to
mainordevelopbranches - Pull requests targeting
mainordevelopbranches
Example workflow trigger:
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main, develop ]- On GitHub: Navigate to
Actionstab in repository - On Pull Requests: Check status at bottom of PR page
- In README: Badges show current status (passing/failing)
Status Badges:
[](...)
[](...)File: .github/workflows/ci.yml
The CI workflow consists of 2 parallel jobs:
- Test Job - Runs full test suite with PostgreSQL
- Security Job - Scans for npm vulnerabilities
Environment:
- Uses
docker-compose.ci.ymlto build and run tests inside Docker - Identical to local development:
docker-compose exec web npm test - PostgreSQL 16 Alpine as database service with healthcheck
- Entrypoint script handles DB readiness + migrations automatically
Steps:
-
Checkout Code
- uses: actions/checkout@v4
-
Build and Run Tests
docker compose -f docker-compose.ci.yml up --build --exit-code-from web --abort-on-container-exit
- Runs all 945 test cases with coverage
- Currently passing: 945/945 (100%)
- Enforces 60% coverage threshold
- Fails if tests fail or coverage drops below threshold
-
Upload Coverage Report
- Uploads coverage directory as GitHub artifact (14-day retention)
- Coverage is bind-mounted to
./coveragefor artifact upload
-
Clean Up
docker compose -f docker-compose.ci.yml down
Key Design Decisions:
- Tests run inside Docker, not on bare runner -- matches local dev exactly
- Single test pass with coverage (not two separate runs)
- Coverage bind-mounted to
./coveragefor artifact upload --exit-code-from webpropagates test exit code to CI
Purpose: Scan for known npm vulnerabilities
Steps:
-
npm Audit (Production - Hard Fail)
npm audit --omit=dev --audit-level=high
- Scans production dependencies only
- Fails CI on high/critical vulnerabilities
- Must be fixed before merge
-
npm Audit (All - Informational)
npm audit --audit-level=moderate
- Scans all dependencies including devDependencies
- Warns on moderate+ vulnerabilities
- Continues on error (informational only)
File: .github/workflows/lint.yml
The lint workflow consists of 2 parallel jobs:
- ESLint Job - JavaScript/Node.js linting
- Prettier Job - Code formatting checks
Purpose: Enforce code quality and best practices
Steps:
-
Run ESLint
npm run lint
- Checks all
.jsfiles - Enforces ESLint rules (see ESLint Configuration)
- Fails CI on any errors
- Checks all
-
Annotate Code (On Failure)
- Adds inline annotations on PR
- Shows exact line with linting error
- Helps developers fix issues quickly
Common ESLint Errors:
// ERROR: no-unused-vars
const unusedVar = 'value'; // ❌ Remove or prefix with _
// ERROR: prefer-const
let name = 'John'; // ❌ Should be const
// ERROR: no-console (in non-test files)
console.log('Debug'); // ❌ Use logger instead
// ERROR: eqeqeq
if (x == 5) {} // ❌ Use === insteadPurpose: Enforce consistent code formatting
Steps:
-
Check Formatting
npm run format:check
- Checks all files against Prettier rules
- Fails CI if any file is not formatted
- Does NOT auto-format (read-only check)
-
Comment on PR (On Failure)
- Posts comment with fix instructions
- Example:
❌ **Code formatting check failed!** Please run `npm run format` to auto-format your code, then commit the changes.
How to Fix:
# Auto-format all files
npm run format
# Commit the changes
git add .
git commit -m "chore: auto-format code with Prettier"
git pushFile: .eslintrc.js
Extends:
eslint:recommended- Standard ESLint rulesprettier- Disables conflicting ESLint rules
Environment:
- Node.js (CommonJS modules)
- ES2021 syntax
- Jest (for test files)
// Unused variables (error)
'no-unused-vars': ['error', { argsIgnorePattern: '^_' }]
// Console usage (warn, except in tests/scripts)
'no-console': ['warn', { allow: ['warn', 'error'] }]
// No debugger statements
'no-debugger': 'error'
// Prefer const over let
'prefer-const': 'error'
// No var declarations
'no-var': 'error'// No dynamic code execution
'no-eval': 'error'
'no-implied-eval': 'error'
'no-new-func': 'error'
// No with statements
'no-with': 'error'// Always use === instead of ==
'eqeqeq': ['error', 'always']
// Always use curly braces
'curly': ['error', 'all']
// 1TBS brace style
'brace-style': ['error', '1tbs']
// No throwing literals
'no-throw-literal': 'error'Formatting rules (indent, quotes, semi, comma-dangle, trailing-spaces, eol-last) are handled by Prettier via eslint-config-prettier. They are not re-declared in .eslintrc.js to avoid conflicts. Prettier configuration in .prettierrc.js is the single source of truth for all formatting decisions.
Test Files (tests/**/*.js, scripts/**/*.js):
- Allows
console.log()(no warnings) - Useful for debugging tests
Ignored Patterns:
node_modules/coverage/dist/build/*.min.js
File: .prettierrc.js
module.exports = {
singleQuote: true, // Use single quotes
trailingComma: 'es5', // Trailing commas where valid in ES5
tabWidth: 2, // 2 spaces per indentation
semi: true, // Always add semicolons
printWidth: 100, // Wrap at 100 characters
arrowParens: 'avoid', // Omit parens when possible (x => x)
endOfLine: 'lf', // Unix line endings
bracketSpacing: true, // Spaces in object literals { foo: bar }
};File: .prettierignore
node_modules/
coverage/
dist/
build/
*.min.js
package-lock.json
.env
.env.test
logs/
backups/
Best Practice: Run linting and tests locally BEFORE pushing to avoid CI failures.
All commands must run inside Docker to match CI and ensure database access:
# 1. Format code
docker-compose exec web npm run format
# 2. Run linter
docker-compose exec web npm run lint
# 3. Run tests
docker-compose exec web npm test
# 4. Check coverage (optional)
docker-compose exec web npm run test:coverageInstall husky and lint-staged for automatic pre-commit checks:
# Install dependencies
npm install --save-dev husky lint-staged
# Initialize husky
npx husky init
# Create pre-commit hook
npx husky add .husky/pre-commit "npx lint-staged"Configuration (add to package.json):
{
"lint-staged": {
"*.js": [
"eslint --fix",
"prettier --write"
]
}
}Benefit: Automatically formats and lints staged files before commit.
# Run specific test file
npm test -- tests/unit/models/User.test.js
# Run tests matching pattern
npm test -- --testNamePattern="should create user"
# Run integration tests only
npm run test:integration
# Run unit tests only
npm run test:unitSymptom: CI fails with test errors
Diagnosis:
# View failed test output in Actions tab
# Look for error messages and stack tracesCommon Causes:
- Database connection issues (PostgreSQL not ready)
- Migration failures (missing/broken SQL)
- Flaky tests (timing/async issues)
- Environment variable mismatches
Fix:
# Run tests locally with same environment
NODE_ENV=test npm test
# Check database initialization
node scripts/init-db.js
# Verify migrations
psql -U ticketing_user -d ticketing_db -c "\dt"Symptom: CI fails with "Coverage for X dropped below Y%"
Diagnosis:
# Generate local coverage report
npm run test:coverage
# View HTML report
npm run test:coverage:htmlThresholds (must meet all):
- Branches: 60%
- Functions: 60%
- Lines: 60%
- Statements: 60%
Fix:
- Add tests for uncovered code
- Focus on branches (if/else, switch, ternary)
- Cover error handlers
- Test edge cases
Symptom: Lint workflow fails with ESLint errors
Diagnosis:
# Run ESLint locally
npm run lintCommon Errors:
// no-unused-vars
const unused = 'value';
// Fix: Remove or prefix with underscore
const _unused = 'value';
// prefer-const
let name = 'John';
// Fix: Use const if not reassigned
const name = 'John';
// no-console (outside tests)
console.log('Debug');
// Fix: Use logger
logger.debug('Debug');
// eqeqeq
if (x == 5) {}
// Fix: Use strict equality
if (x === 5) {}Auto-Fix:
# Auto-fix most linting issues
npm run lint:fixSymptom: Lint workflow fails with formatting errors
Diagnosis:
# Check which files need formatting
npm run format:checkFix:
# Auto-format all files
npm run format
# Commit changes
git add .
git commit -m "chore: auto-format code with Prettier"Symptom: Security job fails with vulnerability warnings
Diagnosis:
# Check vulnerabilities locally
npm audit
# See production-only vulnerabilities
npm audit --productionFix:
# Auto-fix vulnerabilities (if possible)
npm audit fix
# Force fix (may cause breaking changes)
npm audit fix --force
# Manual update
npm update <package>
# If no fix available, document in PR
# Add exception with justificationSymptom: CI fails with "ECONNREFUSED" or "pg_isready timeout"
Diagnosis:
- PostgreSQL service didn't start in time
- Health check failed
Fix:
- Workflow already includes health checks
- Should auto-retry with
--health-interval 10s - If persistent, check GitHub Actions status page
CI Workflow Badge:
[](https://github.com/itheCreator1/KNII_Ticketing/actions/workflows/ci.yml)Lint Workflow Badge:
[](https://github.com/itheCreator1/KNII_Ticketing/actions/workflows/lint.yml)Coverage Badge (via Codecov):
[](https://codecov.io/gh/itheCreator1/KNII_Ticketing)Custom Badge Colors:
-
Create Feature Branch
git checkout -b feature/my-feature
-
Write Code + Tests
- Add tests for new features
- Maintain or improve coverage
-
Local Validation
npm run format # Format code npm run lint # Check linting npm test # Run tests npm run test:coverage # Check coverage
-
Commit Changes
git add . git commit -m "feat: add new feature - Implemented feature X - Added tests with 95% coverage - Updated documentation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
-
Push and Create PR
git push -u origin feature/my-feature
-
Watch CI/CD Results
- CI workflow must pass
- Lint workflow must pass
- Coverage must meet thresholds
-
Address Failures (if any)
# Fix issues locally npm run lint:fix npm run format npm test # Commit fixes git add . git commit -m "fix: address CI failures" git push
-
Merge After Approval
- CI/CD passes ✅
- Code reviewed ✅
- Approved by maintainer ✅
-
Always Use Logger (not console.log)
// ❌ WRONG (fails linting) console.log('User created'); // ✅ CORRECT logger.info('User created', { userId: user.id });
-
Write Testable Code
// ✅ Testable (pure function) function calculateTotal(items) { return items.reduce((sum, item) => sum + item.price, 0); } // ❌ Hard to test (side effects) function processOrder() { const items = fetchItemsFromDB(); const total = items.reduce(...); saveToDatabase(total); }
-
Use Environment Variables
// ✅ CI-friendly const dbUrl = process.env.DATABASE_URL; // ❌ Hardcoded const dbUrl = 'postgresql://localhost:5432/mydb';
-
Mock External Services
// ✅ Mock in tests jest.mock('../services/emailService'); // Test doesn't send real emails test('should send welcome email', () => { userService.createUser({ email: 'test@example.com' }); expect(emailService.sendWelcomeEmail).toHaveBeenCalled(); });
Monthly Tasks:
- Update dependencies (
npm update) - Run security audit (
npm audit) - Review and update coverage thresholds
- Check GitHub Actions usage quota
When Adding Features:
- Add tests (aim for 80%+ coverage)
- Run linting locally before push
- Update documentation
- Verify CI passes before requesting review
When Updating Dependencies:
- Check for breaking changes
- Run full test suite locally
- Monitor CI for unexpected failures
- Update lockfile (
npm ci)
- Node.js Development Rules - Coding standards and patterns
- Testing Guidelines - Test structure and best practices
- Git Workflow - Branching strategy and commit standards
- Debugging Guide - Troubleshooting CI and test failures
Last Updated: February 2026 Version: 2.4.0 Maintained By: KNII Development Team