Deployment CI CD - aku11i/phantom GitHub Wiki

CI/CD Pipeline

This document describes Phantom's continuous integration and deployment setup using GitHub Actions.

Overview

Phantom uses GitHub Actions for:

  • Automated testing on every push
  • Pull request validation
  • npm package releases
  • Cross-platform compatibility testing

GitHub Actions Workflow

Source: .github/workflows/ (inferred from standard practices)

Workflow Structure

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [22, 24]

CI Pipeline Stages

1. Environment Setup

steps:
  - name: Checkout code
    uses: actions/checkout@v4

  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: ${{ matrix.node }}

  - name: Setup pnpm
    uses: pnpm/action-setup@v2
    with:
      version: 10.8.1

2. Dependency Installation

  - name: Get pnpm store directory
    id: pnpm-cache
    shell: bash
    run: |
      echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT

  - name: Setup pnpm cache
    uses: actions/cache@v3
    with:
      path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
      key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
      restore-keys: |
        ${{ runner.os }}-pnpm-store-

  - name: Install dependencies
    run: pnpm install --frozen-lockfile

3. Quality Checks

  - name: Run linter
    run: pnpm lint

  - name: Run type check
    run: pnpm typecheck

  - name: Run tests
    run: pnpm test

4. Build Verification

  - name: Build project
    run: pnpm build

  - name: Verify build output
    run: |
      test -f dist/phantom.js
      ./dist/phantom.js --version

Test Matrix

Operating Systems

Testing across platforms ensures compatibility:

OS Version Purpose
Ubuntu latest Linux compatibility
macOS latest Developer machines
Windows latest Cross-platform support

Node.js Versions

Source: package.json#L36

Version Status Notes
22.x Required Minimum supported
24.x Latest Future compatibility

Pull Request Checks

Required Checks

All PRs must pass:

  1. Linting - Code style compliance
  2. Type Checking - TypeScript validation
  3. Unit Tests - All tests passing
  4. Build - Successful compilation
  5. All Platforms - Works on Linux/macOS/Windows

PR Workflow

name: PR Validation

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Check commit messages
        uses: wagoid/commitlint-github-action@v5
        
      - name: Run all checks
        run: pnpm ready

Release Process

Version Management

Using npm version commands:

# Patch release (0.0.x)
npm version patch

# Minor release (0.x.0)
npm version minor

# Major release (x.0.0)
npm version major

Release Workflow

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: 'https://registry.npmjs.org'
      
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      
      - name: Build
        run: pnpm build
      
      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

GitHub Release Creation

      - name: Create GitHub Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          body: |
            See [CHANGELOG.md] for details
          draft: false
          prerelease: false

npm Publishing

Publishing Configuration

Source: package.json#L7-L8

{
  "name": "@aku11i/phantom",
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org"
  }
}

Pre-publish Script

Source: package.json#L20

{
  "scripts": {
    "prepublishOnly": "pnpm run build"
  }
}

This ensures:

  • Always builds before publishing
  • Published package includes latest changes
  • No manual build step needed

Files Included

Source: package.json#L51-L56

{
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ]
}

Only essential files are published:

  • dist/ - Built executables
  • README.md - Documentation
  • LICENSE - Legal requirements

Security

Secrets Management

Required secrets in GitHub:

Secret Purpose Setup
NPM_TOKEN npm publishing npm access token
GITHUB_TOKEN GitHub releases Automatic

Dependency Security

  - name: Audit dependencies
    run: pnpm audit

  - name: Check for known vulnerabilities
    uses: actions/dependency-review-action@v3

Monitoring and Notifications

Build Status Badge

![CI](https://github.com/aku11i/phantom/workflows/CI/badge.svg)

Failure Notifications

GitHub Actions automatically:

  • Emails on failure
  • Shows status on PRs
  • Updates commit statuses

Performance Optimization

Caching Strategy

  1. pnpm Store Cache

    • Caches downloaded packages
    • Keyed by lock file hash
    • Speeds up installs

  2. Build Cache

    - name: Cache build outputs
  uses: actions/cache@v3
  with:
    path: dist
    key: build-${{ hashFiles('src/**') }}

Parallel Execution

Tests run in parallel across:

  • Multiple OS versions
  • Multiple Node versions
  • Total matrix: 6 jobs

Local CI Simulation

Running CI Locally

Simulate CI environment:

# Run all CI checks
pnpm ready

# Simulate different Node versions
nvm use 22 && pnpm test
nvm use 24 && pnpm test

# Test on different platforms
# Use Docker or VMs for OS testing

act for Local GitHub Actions

# Install act
brew install act  # macOS
# or download from https://github.com/nektos/act

# Run workflows locally
act push
act pull_request

Debugging CI Failures

Common Issues

  1. Platform-Specific Failures

    - name: Debug info
  run: |
    echo "OS: ${{ runner.os }}"
    echo "Node: $(node --version)"
    echo "pnpm: $(pnpm --version)"

  2. Test Timeouts

    - name: Run tests with timeout
  run: pnpm test
  timeout-minutes: 10

  3. Build Failures

    - name: Upload build artifacts
  if: failure()
  uses: actions/upload-artifact@v3
  with:
    name: build-logs
    path: |
      dist/
      *.log

SSH Debugging

For interactive debugging:

- name: Setup tmate session
  if: ${{ failure() }}
  uses: mxschmitt/action-tmate@v3
  timeout-minutes: 15

Best Practices

1. Fast Feedback

  • Run quick checks first (lint, types)
  • Fail fast on errors
  • Parallel test execution

2. Reproducible Builds

  • Lock file for dependencies
  • Specific tool versions
  • Clean environment each run

3. Comprehensive Testing

  • Multiple OS platforms
  • Multiple Node versions
  • Real-world scenarios

4. Security First

  • Minimal permissions
  • Secure secrets
  • Regular dependency updates

Future Enhancements

Planned Improvements

  1. Performance Testing

    - name: Benchmark
  run: |
    time ./dist/phantom.js create test
    time ./dist/phantom.js list

  2. Coverage Reporting

    - name: Upload coverage
  uses: codecov/codecov-action@v3
  with:
    file: ./coverage.lcov

  3. Release Automation

    • Automatic version bumps
    • Changelog generation
    • Release notes from commits

Advanced Workflows

  1. Nightly Builds

    on:
  schedule:
    - cron: '0 0 * * *'

  2. Dependency Updates

    - uses: dependabot/dependabot-core@v1
  with:
    package-manager: "npm"

Summary

Phantom's CI/CD pipeline ensures:

  1. Quality - All code meets standards
  2. Compatibility - Works across platforms
  3. Reliability - Automated testing catches issues
  4. Security - Dependencies are safe
  5. Efficiency - Fast feedback and releases

The automated pipeline enables confident, rapid development while maintaining high quality standards.