blackroad-os-prism-console/docs/ci-workflows.md

CI/CD Workflows

This document describes the continuous integration and deployment workflows for the Prism Console application.

Overview

The project uses GitHub Actions for automated testing, linting, building, and deployment. All workflows are defined in .github/workflows/.

Workflows

1. Test Workflow (test.yml)

Trigger: Push to main/develop, pull requests

Purpose: Run Jest tests across multiple Node.js versions

Jobs:

• Install dependencies
• Run tests with coverage
• Upload coverage to Codecov
• Archive test results

Node.js versions tested: 20.x, 22.x

# Run locally
npm test

Configuration:

• Tests run with --ci flag for cleaner output
• Coverage reports uploaded for Node 20.x only
• Test results archived for 7 days

2. Lint Workflow (lint.yml)

Trigger: Push to main/develop, pull requests

Purpose: Enforce code quality standards

Checks:

1. ESLint - JavaScript/TypeScript linting
2. TypeScript - Type checking
3. Prettier - Code formatting (if configured)

# Run locally
npm run lint
npm run type-check

Failure conditions:

• ESLint errors (warnings allowed)
• TypeScript type errors
• Prettier formatting issues (if enabled)

3. Build Workflow (build.yml)

Trigger: Push to main/develop, pull requests

Purpose: Verify Next.js build succeeds

Steps:

1. Install dependencies
2. Run next build
3. Verify .next directory created
4. Check for standalone output
5. Archive build artifacts

# Run locally
npm run build

Artifacts:

• Build output stored for 7 days
• Excludes cache directory for size reduction

4. Auto Labeler Workflow (auto-labeler.yml)

Trigger: PR opened/updated, issue opened/edited

Purpose: Automatically label PRs and issues

Features:

• File-based labeling - Labels PRs based on changed files
• Size labeling - Adds size labels (xs/s/m/l/xl) based on lines changed
• Issue labeling - Labels issues based on title/body keywords

Label categories:

• component - Component file changes
• pages - Page/route changes
• api - API route changes
• testing - Test file changes
• documentation - Docs changes
• ci/cd - Workflow changes
• dependencies - Package.json changes
• Size labels: size/xs, size/s, size/m, size/l, size/xl

Configuration Files

.github/labels.yml

Defines keyword-based labeling for issues:

- label: "bug"
  keywords:
    - bug
    - error
    - crash

.github/labeler.yml

Defines file path-based labeling for PRs:

component:
  - changed-files:
    - any-glob-to-any-file: 'src/components/**/*.{ts,tsx}'

Branch Protection

Recommended branch protection rules for main:

• Require pull request reviews (1+ approver)
• Require status checks to pass:
  • test workflow
  • lint workflow
  • build workflow
• Require branches to be up to date
• Require conversation resolution
• Require signed commits (optional)

Secrets Configuration

Required secrets (if using all features):

Secret	Purpose	Required
CODECOV_TOKEN	Upload coverage reports	Optional
GITHUB_TOKEN	Automatic (provided by GitHub)	Yes

Add secrets in: Settings → Secrets and variables → Actions

Local Testing of Workflows

Use act to test workflows locally:

# Install act
brew install act

# Run test workflow
act push -j test

# Run all workflows for PR
act pull_request

Workflow Status Badges

Add to README.md:

![Tests](https://github.com/your-org/blackroad-os-prism-console/workflows/Tests/badge.svg)
![Lint](https://github.com/your-org/blackroad-os-prism-console/workflows/Lint/badge.svg)
![Build](https://github.com/your-org/blackroad-os-prism-console/workflows/Build/badge.svg)

Troubleshooting

Workflow fails on npm ci

Cause: Lock file out of sync with package.json

Solution:

rm package-lock.json
npm install
git add package-lock.json
git commit -m "Update package-lock.json"

Tests pass locally but fail in CI

Cause: Environment differences or missing mocks

Solutions:

• Check Node.js version match
• Verify environment variables
• Review test isolation (tests may depend on each other)

Build succeeds locally but fails in CI

Cause: TypeScript errors ignored locally

Solution:

# Run same checks as CI
npm run type-check
npm run build

Labeler not working

Cause: Invalid glob patterns or missing permissions

Solutions:

• Verify glob patterns in .github/labeler.yml
• Check workflow has pull-requests: write permission
• Test patterns locally with glob tools

Performance Optimization

Cache Dependencies

All workflows use npm cache:

- uses: actions/setup-node@v4
  with:
    cache: 'npm'

Parallel Jobs

Tests run in parallel across Node versions using matrix strategy:

strategy:
  matrix:
    node-version: [20.x, 22.x]

Limit Test Workers

CI uses fewer workers for stability:

npm test -- --maxWorkers=2

Monitoring

View workflow runs:

• GitHub: Actions tab → Select workflow
• Notifications: Enable in Settings → Notifications

Check average workflow duration:

• Target: < 5 minutes for test workflow
• Target: < 3 minutes for lint workflow
• Target: < 5 minutes for build workflow

Future Enhancements

• Add E2E testing with Playwright/Cypress
• Deploy preview environments for PRs
• Add performance benchmarking
• Integrate security scanning (Snyk, Dependabot)
• Add bundle size tracking
• Implement canary deployments

Resources

• GitHub Actions Documentation
• Next.js CI/CD Guide
• Actions Labeler
• Codecov Documentation