Krakaw Shared GitHub Actions Workflows

Reusable workflows for all Krakaw organization repositories.

Available Workflows

1. Node.js CI (node-ci.yml)

Standardized CI pipeline for Node.js/TypeScript projects with quality gates:

• ✅ Dependency installation (with private repo support)
• ✅ Security audit (npm audit)
• ✅ Linting (ESLint, Prettier)
• ✅ Type checking (TypeScript)
• ✅ Build verification
• ✅ Unit/integration tests
• ✅ Coverage reporting (Codecov)

Usage

Create .github/workflows/ci.yml in your repository:

name: CI

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

jobs:
  ci:
    uses: Krakaw/.github/.github/workflows/node-ci.yml@main

Configuration Options

Advanced Examples

Skip tests temporarily:

jobs:
  ci:
    uses: Krakaw/.github/.github/workflows/node-ci.yml@main
    with:
      run-test: false

Monorepo with custom working directory:

jobs:
  ci:
    uses: Krakaw/.github/.github/workflows/node-ci.yml@main
    with:
      working-directory: './packages/api'

Private npm dependencies (e.g., @Krakaw packages):

jobs:
  ci:
    uses: Krakaw/.github/.github/workflows/node-ci.yml@main
    secrets:
      GH_PAT: ${{ secrets.GH_PAT }}

Different Node version:

jobs:
  ci:
    uses: Krakaw/.github/.github/workflows/node-ci.yml@main
    with:
      node-version: '20'

Allow test failures (migration period):

jobs:
  ci:
    uses: Krakaw/.github/.github/workflows/node-ci.yml@main
    with:
      test-continue-on-error: true

2. Docker Build and Push (docker-build.yml)

Multi-service Docker image build and publish to GitHub Container Registry.

Usage

Create .github/workflows/docker.yml in your repository:

name: Docker

on:
  push:
    branches: [main]
    tags: ['v*']

jobs:
  docker:
    uses: Krakaw/.github/.github/workflows/docker-build.yml@main
    with:
      services: '[{"name": "default", "dockerfile": "Dockerfile", "context": "."}]'
      platforms: 'linux/amd64,linux/arm64'
      push: true

Configuration Options

Multi-Service Example

For monorepos with multiple Dockerfiles:

jobs:
  docker:
    uses: Krakaw/.github/.github/workflows/docker-build.yml@main
    with:
      services: |
        [
          {"name": "api", "dockerfile": "Dockerfile.api", "context": "./packages/api"},
          {"name": "worker", "dockerfile": "Dockerfile.worker", "context": "./packages/worker"}
        ]
      platforms: 'linux/amd64,linux/arm64'
      push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}

3. NPM Publish (npm-publish.yml)

Reusable workflow for publishing @krakaw packages to npm with provenance attestation, automatic changelog generation from conventional commits, GitHub release creation, and Telegram notifications.

Features

• ✅ Full CI gate: lint → typecheck → test → build (each step skips gracefully if script not present)
• ✅ npm publish with provenance attestation (--provenance --access public)
• ✅ Changelog generated from conventional commits (feat/fix/perf/breaking) using git log
• ✅ GitHub Release created automatically with the changelog as release notes
• ✅ Telegram notification on success and failure
• ✅ Dry-run mode via workflow_dispatch input (safe to test before real publish)
• ✅ Configurable: package_path, node_version, registry_url

Usage

Create .github/workflows/npm-publish.yml in your repository:

name: Publish to npm

on:
  push:
    tags:
      - 'v*'
  workflow_dispatch:
    inputs:
      dry_run:
        description: 'Dry run (skip actual publish and release)'
        required: false
        default: true
        type: boolean

jobs:
  publish:
    uses: Krakaw/.github/.github/workflows/npm-publish.yml@main
    with:
      dry_run: ${{ inputs.dry_run || false }}
    secrets: inherit

See .github/workflows/npm-publish-example.yml in this repo for a full annotated example including monorepo patterns.

Configuration Options

Required Secrets

Configure these as Krakaw org secrets to share them across all repos automatically.

Outputs

Conventional Commits Support

The workflow parses commit messages since the previous semver tag and groups them into:

Monorepo Usage

For repos with multiple packages (e.g., one tag per package):

jobs:
  publish-webhooks:
    uses: Krakaw/.github/.github/workflows/npm-publish.yml@main
    with:
      package_path: packages/webhooks
    secrets: inherit

  publish-notifications:
    uses: Krakaw/.github/.github/workflows/npm-publish.yml@main
    with:
      package_path: packages/notifications
    secrets: inherit

Packages Using This Workflow

• @krakaw/webhooks
• @krakaw/notifications
• @krakaw/command-center-client
• @krakaw/stripe-billing

Development

Testing Workflows Locally

Use act to test workflows locally:

# Install act
brew install act

# Test the CI workflow
act pull_request -W .github/workflows/node-ci.yml

Contributing

1. Create a feature branch: git checkout -b feature/new-workflow
2. Add/modify workflow in .github/workflows/
3. Update this README with usage docs
4. Test with act or in a test repository
5. Open a PR

Best Practices

• Version your workflow calls: Use @main for latest, or pin to a specific commit/tag for stability
• Use semantic versioning: Tag releases (e.g., v1.0.0) for breaking changes
• Document inputs: Add clear descriptions and examples for all workflow inputs
• Test before merging: Validate workflows in a test repository before merging to main
• Keep workflows DRY: Extract common patterns into reusable workflows

Roadmap

Future workflow ideas:

• npm-publish.yml - Automated npm package publishing ✅
• dependency-update.yml - Automated dependency updates (Dependabot alternative)
• security-scan.yml - CodeQL + Trivy security scanning
• performance-test.yml - Load testing and benchmarking
• deploy-production.yml - Standardized deployment pipeline

Support

Questions or issues? Open an issue in this repository or reach out in the Krakaw Discord.