@lilith/forgejo-ci

Reusable Forgejo Actions workflows, composite actions, and CI/CD templates for the Lilith ecosystem.

Features

• Workflow Templates - Pre-configured CI/CD pipelines for Node.js, Docker, E2E testing, and deployment
• Composite Actions - Reusable action blocks for common setup tasks
• Service Containers - Ready-to-use PostgreSQL, Redis, Meilisearch, MinIO definitions
• Monorepo Support - Affected package detection for efficient builds
• Forgejo NPM Registry - Built-in support for forge.black.lan package registry

Installation

pnpm add -D @lilith/forgejo-ci

Quick Start

Initialize Forgejo Actions in your project:

npx @lilith/forgejo-ci init

This copies all workflow templates and composite actions to .forgejo/ in your project.

Available Templates

Workflows

Template	Description
node-ci.yml	Standard Node.js CI with typecheck, lint, test, build
npm-publish.yml	Publish packages to Forgejo NPM registry
docker-build.yml	Build and push Docker images
e2e-web.yml	Playwright E2E tests for web apps
e2e-electron.yml	Playwright E2E tests for Electron apps (with Xvfb)
deploy-vps.yml	SSH deployment to VPS with docker-compose
monorepo-affected.yml	Only build/test affected packages

Composite Actions

Action	Description
setup-pnpm	Setup pnpm with caching
setup-node	Full Node.js + pnpm + registry setup
forgejo-npm-auth	Configure .npmrc for Forgejo registry
affected-packages	Detect which packages changed

Service Containers

Service	Image
postgres.yml	PostgreSQL 16 Alpine
redis.yml	Redis 7 Alpine / Redis Stack
meilisearch.yml	Meilisearch v1.11
minio.yml	MinIO S3-compatible storage

Usage Examples

Basic Node.js CI

Copy templates/workflows/node-ci.yml to .forgejo/workflows/ci.yml:

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm typecheck
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm build

Publishing to Forgejo NPM Registry

Configure your package.json with the _ field:

{
  "name": "@lilith/my-package",
  "version": "1.0.0",
  "_": {
    "registry": "forgejo",
    "publish": true,
    "build": true
  }
}

Then use templates/workflows/npm-publish.yml. Required secret: NPM_TOKEN

E2E Testing with Services

jobs:
  e2e:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.57.0-noble

    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
          POSTGRES_DB: test
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

      redis:
        image: redis:7-alpine
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    env:
      DATABASE_URL: postgresql://test:test@postgres:5432/test
      REDIS_URL: redis://redis:6379

    steps:
      - uses: actions/checkout@v4
      - run: corepack enable && corepack prepare pnpm@9 --activate
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm test:e2e

VPS Deployment

Required secrets:

• VPS_HOST - Hostname or IP
• VPS_USER - SSH username
• VPS_SSH_KEY - Private SSH key

- name: Deploy
  run: |
    ssh ${{ secrets.VPS_USER }}@${{ secrets.VPS_HOST }} << 'DEPLOY'
      cd /opt/app
      docker compose pull
      docker compose up -d --remove-orphans
    DEPLOY

Using Composite Actions

After running npx @lilith/forgejo-ci init, use local actions:

steps:
  - uses: actions/checkout@v4

  - uses: ./.forgejo/actions/setup-node
    with:
      node-version: 22
      pnpm-version: 9

  - uses: ./.forgejo/actions/forgejo-npm-auth
    with:
      token: ${{ secrets.NPM_TOKEN }}

  - run: pnpm publish

Monorepo Affected Detection

jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      packages: ${{ steps.affected.outputs.packages }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: ./.forgejo/actions/affected-packages
        id: affected

  build:
    needs: detect
    if: needs.detect.outputs.packages != ''
    runs-on: ubuntu-latest
    steps:
      - run: echo "Building ${{ needs.detect.outputs.packages }}"

Programmatic API

import {
  createWorkflowConfig,
  transformWorkspaceDeps,
  detectAffectedPackages,
} from '@lilith/forgejo-ci';

// Create workflow configuration
const config = createWorkflowConfig({
  name: 'My CI',
  type: 'node-ci',
  nodeVersion: '22',
  services: [{ type: 'postgres' }, { type: 'redis' }],
});

// Transform workspace:* dependencies for publishing
const result = transformWorkspaceDeps({
  '@lilith/ui': 'workspace:*',
  '@lilith/config': 'workspace:^1.0.0',
  'lodash': '^4.17.21',
});
// result.transformed = { '@lilith/ui': '*', '@lilith/config': '^1.0.0', 'lodash': '^4.17.21' }

// Detect affected packages
const affected = await detectAffectedPackages([
  'packages/ui/src/Button.tsx',
  'packages/config/tsconfig.json',
]);
// affected = { packages: ['ui', 'config'], hasChanges: true, isAll: false }

CLI Commands

# Initialize Forgejo Actions in current directory
npx @lilith/forgejo-ci init

# Initialize in specific directory
npx @lilith/forgejo-ci init ./my-project

# List available templates
npx @lilith/forgejo-ci list

# Show help
npx @lilith/forgejo-ci help

Required Secrets by Workflow

Workflow	Secrets
npm-publish.yml	NPM_TOKEN
docker-build.yml	REGISTRY_TOKEN
deploy-vps.yml	VPS_HOST, VPS_USER, VPS_SSH_KEY

Integration with @lilith/playwright-e2e-docker

This package works seamlessly with @lilith/playwright-e2e-docker for E2E testing:

jobs:
  e2e:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.57.0-noble
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install
      - run: pnpm test:e2e  # Uses @lilith/playwright-e2e-docker

Contributing

This package is part of the Lilith Platform ecosystem. Contributions should follow the project's coding standards and be submitted via the Forgejo repository.

License

MIT

Test ALL 1767646380