NC-Webapps Shared Workflows

Reusable GitHub Actions workflows for the nc-webapps ecosystem.

Available Workflows

Workflow	Purpose
deploy-adonisjs.yml	Deploy AdonisJS microapps to production
deploy-microapp.yml	Legacy deploy (deprecated, use deploy-adonisjs)
ai-kb-ingest.yml	Ingest repo to AI Knowledge Base

---

deploy-adonisjs.yml

Standardized deployment for AdonisJS apps with:

• ✅ Test job (PostgreSQL + optional Redis)
• ✅ TypeScript compilation check
• ✅ Database migrations
• ✅ PM2 process management
• ✅ Health checks with retries
• ✅ Clean builds (rm -rf build && node_modules)
• ✅ Security checks (runs automatically on every deploy)
• ✅ Playwright E2E tests (opt-in via has_e2e: true)
• ✅ Caddy reverse-proxy verification (when domain is set)

Inputs

Input	Required	Default	Description
app_name	✅	-	App name (bankrec, pulse, etc.)
port	✅	-	Port number (3342, 3335, etc.)
node_version	❌	20	Node.js version
needs_redis	❌	false	Include Redis in test job
health_endpoint	❌	/health	Health check URL path
run_migrations	❌	true	Run node ace migration:run
skip_tests	❌	false	Skip test job
post_deploy_script	❌	""	Script to run after PM2 restart
has_e2e	❌	false	Run Playwright E2E tests after build (requires playwright.config.ts in repo)
needs_jwt_keys	❌	false	Generate JWT keys for testing (identity service)
domain	❌	""	Service domain (e.g., bankrec.nc-webapps.com) for Caddy reverse-proxy verification
security_level	❌	"standard"	Security check level: standard, strict (warnings become blocks), relaxed (all warnings)
nvm_node_version	❌	""	If set, use this Node version via nvm on the server (e.g., "24"). Requires nvm installed for deploy user.

Secrets

Secret	Required	Description
SSH_PRIVATE_KEY	✅	SSH key for droplet
DROPLET_HOST	✅	Server IP/hostname
APP_KEY	✅	AdonisJS app key
DATABASE_URL	✅	PostgreSQL connection string
REDIS_URL	❌	Redis connection string
HUB_JWT_SECRET	❌	Hub SSO JWT secret
HUB_API_KEY	❌	Hub API key
JWT_PRIVATE_KEY	❌	JWT private key PEM (identity service)
JWT_PUBLIC_KEY	❌	JWT public key PEM (identity service)
EXTRA_ENV	❌	Additional env vars (newline-separated)

Basic Usage

# .github/workflows/deploy.yml
name: Deploy MyApp

on:
  push:
    branches: [main]

jobs:
  deploy:
    uses: nc-webapps/shared-workflows/.github/workflows/deploy-adonisjs.yml@main
    with:
      app_name: myapp
      port: 3340
    secrets:
      SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
      DROPLET_HOST: ${{ secrets.DROPLET_HOST }}
      APP_KEY: ${{ secrets.APP_KEY }}
      DATABASE_URL: ${{ secrets.DATABASE_URL }}

With Redis & Extra Env Vars

jobs:
  deploy:
    uses: nc-webapps/shared-workflows/.github/workflows/deploy-adonisjs.yml@main
    with:
      app_name: pulse
      port: 3335
      needs_redis: true
      post_deploy_script: |
        su - deploy -c "pm2 restart hub || true"
    secrets:
      SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
      DROPLET_HOST: ${{ secrets.DROPLET_HOST }}
      APP_KEY: ${{ secrets.APP_KEY }}
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
      REDIS_URL: ${{ secrets.REDIS_URL }}
      HUB_JWT_SECRET: ${{ secrets.HUB_JWT_SECRET }}
      EXTRA_ENV: |
        AI_KB_URL=${{ secrets.AI_KB_URL }}
        S3_ACCESS_KEY=${{ secrets.S3_ACCESS_KEY }}

E2E Testing

When has_e2e: true is set, a dedicated e2e job runs in parallel with unit tests:

1. Provisions PostgreSQL (and Redis if needs_redis: true)
2. Installs dependencies and Chromium via Playwright
3. Runs database migrations and builds the application
4. Executes npx playwright test -- Playwright's webServer config starts the built app automatically
5. Uploads the Playwright HTML report and any test artifacts as workflow artifacts (retained 7 days)

The E2E job is skipped when skip_tests: true. Deploy proceeds only if E2E passes (or was skipped).

Prerequisites in the consuming repo:

• playwright.config.ts at the repo root, with a webServer block pointing at the built app
• @playwright/test in devDependencies
• E2E test files under e2e/ or tests/e2e/
• Tests should target Chromium only in CI (the workflow installs only Chromium)

See examples/deploy-with-e2e.yml for a complete example, and examples/playwright.config.ts for a starter Playwright config.

Security Checks

A security job runs automatically on every deploy (no opt-in needed). It checks for:

• BLOCK -- CORS origin: true combined with credentials: true
• BLOCK -- .env file tracked in git
• BLOCK -- Hardcoded secrets/credentials in source code
• WARN -- Missing config/shield.ts (CSRF protection)
• WARN -- No auth middleware found in route definitions

The security_level input controls severity:

Level	Behavior
standard	Blocks fail the pipeline; warnings are advisory
strict	Warnings are promoted to blocks (all findings fail the pipeline)
relaxed	Blocks are demoted to warnings (pipeline always passes)

Use relaxed temporarily if a false positive blocks your deploy, and follow up with a fix.

---

ai-kb-ingest.yml

Automatically ingest repo content to AI Knowledge Base on push to main.

Usage

Copy to your repo's .github/workflows/ai-kb-ingest.yml:

name: Ingest to AI-KB

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  ingest:
    uses: nc-webapps/shared-workflows/.github/workflows/ai-kb-ingest.yml@main
    secrets:
      AI_KB_API_KEY: ${{ secrets.AI_KB_API_KEY }}

---

Port Assignments

App	Port
hub	3000
identity	3331
shipstream	3334
pulse	3335
miles	3336
ledger	3337
docai	3339
bankrec	3342

---

Migration Guide

To migrate an existing app to shared workflows:

1. Backup your current .github/workflows/deploy.yml

2. Replace with shared workflow call (see examples above)

3. Ensure secrets are set in repo settings:

   gh secret list --repo nc-webapps/myapp
   

4. Test with manual trigger:

   gh workflow run deploy.yml --repo nc-webapps/myapp
   

5. Monitor deployment:

   gh run watch --repo nc-webapps/myapp
   

---

Examples

See examples/ directory for complete workflow files:

• deploy-bankrec.yml - Simple app (no Redis)
• deploy-pulse.yml - Complex app (Redis + extra env vars + post-deploy)
• deploy-with-e2e.yml - App with Playwright E2E tests enabled
• playwright.config.ts - Starter Playwright config for AdonisJS apps