@molecule/api-ci-github-actions

GitHub Actions CI/CD templates and utilities for molecule.dev.

Provides pre-built workflow configurations and a YAML generator for setting up CI/CD pipelines.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import {
  workflows,
  commonSteps,
  generateWorkflow,
  workflowPath,
} from '@molecule/api-ci-github-actions'
import type { WorkflowConfig } from '@molecule/api-ci-github-actions'

// Use a pre-built workflow
const ciWorkflow = workflows.ci()
const yaml = generateWorkflow(ciWorkflow)
// Write to .github/workflows/ci.yml

// Build a custom workflow using common steps
const customWorkflow: WorkflowConfig = {
  name: 'Custom CI',
  on: {
    push: { branches: ['main', 'develop'] },
    pull_request: { branches: ['main'] },
  },
  jobs: {
    build: {
      'runs-on': 'ubuntu-latest',
      steps: [
        commonSteps.checkout(),
        commonSteps.setupNode('20'),
        commonSteps.npmInstall(),
        commonSteps.npmLint(),
        commonSteps.npmBuild(),
        commonSteps.npmTest(),
      ],
    },
  },
}

Type

infrastructure

Installation

npm install @molecule/api-ci-github-actions

API

Interfaces

WorkflowTrigger

Defines when a workflow runs — which branches, tags, paths, schedules, or manual triggers activate it. Maps to the on: key in workflow YAML.

interface WorkflowTrigger {
  push?: {
    branches?: string[]
    tags?: string[]
    paths?: string[]
    'paths-ignore'?: string[]
  }
  pull_request?: {
    branches?: string[]
    types?: string[]
  }
  workflow_dispatch?: {
    inputs?: Record<
      string,
      {
        description: string
        required?: boolean
        default?: string
        type?: 'string' | 'boolean' | 'choice' | 'environment'
        options?: string[]
      }
    >
  }
  schedule?: Array<{ cron: string }>
  delete?: Record<string, never>
}

WorkflowStep

A single step within a workflow job. Each step either runs a shell command (run) or uses a GitHub Action (uses), with optional environment variables and conditionals.

interface WorkflowStep {
  name?: string
  id?: string
  uses?: string
  run?: string
  with?: Record<string, string | number | boolean>
  env?: Record<string, string>
  if?: string
  'working-directory'?: string
  'continue-on-error'?: boolean
  'timeout-minutes'?: number
}

WorkflowJob

A workflow job that runs on a specified runner. Contains an ordered list of steps, optional service containers (e.g. Postgres, Redis), matrix strategy, and job dependencies.

interface WorkflowJob {
  name?: string
  'runs-on': string | string[]
  needs?: string | string[]
  if?: string
  env?: Record<string, string>
  strategy?: {
    matrix?: Record<string, unknown[]>
    'fail-fast'?: boolean
    'max-parallel'?: number
  }
  steps: WorkflowStep[]
  services?: Record<
    string,
    {
      image: string
      ports?: string[]
      env?: Record<string, string>
      options?: string
    }
  >
  outputs?: Record<string, string>
  'timeout-minutes'?: number
}

WorkflowConfig

Complete workflow configuration that maps to a .github/workflows/*.yml file. Contains the workflow name, trigger rules, optional global environment variables, concurrency settings, and one or more jobs.

interface WorkflowConfig {
  name: string
  on: WorkflowTrigger
  env?: Record<string, string>
  concurrency?: {
    group: string
    'cancel-in-progress'?: boolean
  }
  jobs: Record<string, WorkflowJob>
}

Functions

toYAML(config)

Serializes a workflow configuration object to a YAML string suitable for writing to .github/workflows/*.yml.

function toYAML(config: WorkflowConfig): string

• config — The workflow configuration to serialize.

Returns: The YAML string representation of the workflow.

generateWorkflow(config)

Generates a complete workflow file with a header comment indicating it was auto-generated. The output is ready to write to .github/workflows/.

function generateWorkflow(config: WorkflowConfig): string

• config — The workflow configuration to generate.

Returns: The complete YAML file content including the auto-generated header.

workflowPath(name)

Returns the conventional file path for a GitHub Actions workflow file.

function workflowPath(name: string): string

• name — The workflow name (e.g. 'ci', 'release').

Returns: The path relative to the repo root (e.g. .github/workflows/ci.yml).

Constants

commonSteps

Reusable step factory functions for common CI operations. Each method returns a WorkflowStep that can be included in any workflow job's steps array.

const commonSteps: {
  checkout: (options?: { 'fetch-depth'?: number }) => WorkflowStep
  setupNode: (version?: string, options?: { registryUrl?: string }) => WorkflowStep
  npmInstall: () => WorkflowStep
  npmBuild: () => WorkflowStep
  npmTest: () => WorkflowStep
  npmLint: () => WorkflowStep
  cacheNodeModules: () => WorkflowStep
  stageUp: (driver?: string) => WorkflowStep
  stageDown: () => WorkflowStep
}

workflows

Pre-built workflow template factories. Each method returns a complete WorkflowConfig ready to pass to generateWorkflow() and write to disk.

const workflows: {
  ci: () => WorkflowConfig
  projectCi: (options?: { database?: boolean; e2e?: boolean }) => WorkflowConfig
  ciMatrix: (nodeVersions?: string[]) => WorkflowConfig
  release: () => WorkflowConfig
  integrationTests: () => WorkflowConfig
  stagingDeploy: (options?: { driver?: string; excludeBranches?: string[] }) => WorkflowConfig
  stagingTeardown: () => WorkflowConfig
}

Injection Notes

Gotchas the generated workflows already account for — keep them in mind when building custom configs:

• setupNode() caches the npm download cache, which works with npm ci. Do NOT add cacheNodeModules() to an npm ci pipeline — npm ci deletes node_modules before installing, so that cache is discarded every run.
• Publishing to npm requires registry-url on the setup-node step (see workflows.release()); NODE_AUTH_TOKEN alone is silently ignored and npm publish fails with ENEEDAUTH.
• workflows.stagingDeploy() / stagingTeardown() with the docker-compose driver deploy to the machine running the workflow — on GitHub-hosted runners the environment dies when the job ends; use a persistent self-hosted runner.
• Version-like strings stay quoted in the YAML output on purpose: unquoted, '20.10' parses back as the float 20.1 and installs the wrong Node.