API Reference

Complete reference for the DotGitHub TypeScript API.

Core Types
Construct Interface
Workflow Constructs
Action Constructs
Utility Functions
Configuration Types

Core Types

GitHubConstruct

The base class that all constructs extend.

abstract class GitHubConstruct {
  readonly name: string;
  readonly version?: string;
  readonly description?: string;

  validate?(stack: GitHubStack): void | Promise<void>;
  describe?(): ConstructDescription | Promise<ConstructDescription>;
  synthesize(stack: GitHubStack): Promise<void>;
}

GitHubStack

Represents a stack configuration and provides context for construct execution.

interface GitHubStack {
  readonly name: string;
  readonly config: Record<string, any>;
  readonly constructs: string[];
}

ConstructDescription

Metadata about a construct.

interface ConstructDescription {
  name: string;
  version?: string;
  description?: string;
  author?: string;
  repository?: string;
  license?: string;
  keywords?: string[];
  category?: string;
  tags?: string[];
  minDotGithubVersion?: string;
  configSchema?: z.ZodSchema;
}

Construct Interface

validate(stack: GitHubStack): void

Validates the stack configuration. Should throw an error if the configuration is invalid.

validate(stack: GitHubStack): void {
  const schema = z.object({
    environment: z.enum(['development', 'staging', 'production']),
    timeout: z.number().min(1).max(60).default(10)
  });

  schema.parse(stack.config);
}

describe(): ConstructDescription

Returns metadata about the construct.

describe(): ConstructDescription {
  return {
    name: this.name,
    version: this.version,
    description: this.description,
    author: 'Your Name',
    repository: 'https://github.com/yourusername/yourrepo',
    license: 'MIT',
    keywords: ['ci', 'github-actions'],
    category: 'ci',
    tags: ['ci', 'testing'],
    minDotGithubVersion: '1.0.0'
  };
}

synthesize(stack: GitHubStack): Promise

Generates workflow content for the stack.

async synthesize(stack: GitHubStack): Promise<void> {
  const wf = new WorkflowConstruct(stack, 'ci', {
    name: 'CI Workflow',
    on: { push: { branches: ['main'] } },
    jobs: {}
  });

  // Add jobs and steps...
}

Workflow Constructs

WorkflowConstruct

Creates and configures GitHub workflows.

class WorkflowConstruct {
  constructor(stack: GitHubStack, id: string, props: WorkflowProps);
}

WorkflowProps

interface WorkflowProps {
  name: string;
  on: WorkflowTrigger;
  jobs: Record<string, JobDefinition>;
  env?: Record<string, string>;
  defaults?: WorkflowDefaults;
  concurrency?: ConcurrencyConfig;
}

WorkflowTrigger

interface WorkflowTrigger {
  push?: {
    branches?: string[];
    tags?: string[];
    paths?: string[];
    pathsIgnore?: string[];
  };
  pull_request?: {
    branches?: string[];
    paths?: string[];
    pathsIgnore?: string[];
  };
  schedule?: Array<{
    cron: string;
  }>;
  workflow_dispatch?: {
    inputs?: Record<string, WorkflowInput>;
  };
  repository_dispatch?: {
    types?: string[];
  };
  // ... other trigger types
}

JobConstruct

Creates and configures workflow jobs.

class JobConstruct {
  constructor(workflow: WorkflowConstruct, id: string, props: JobProps);
}

JobProps

interface JobProps {
  'runs-on': string | string[];
  needs?: string | string[];
  if?: string;
  steps: Step[];
  strategy?: StrategyConfig;
  env?: Record<string, string>;
  defaults?: JobDefaults;
  timeoutMinutes?: number;
  continueOnError?: boolean;
  container?: ContainerConfig;
  services?: Record<string, ServiceConfig>;
}

StrategyConfig

interface StrategyConfig {
  matrix: Record<string, any[]>;
  failFast?: boolean;
  maxParallel?: number;
}

Action Constructs

Actions

Provides type-safe access to GitHub Actions.

class Actions {
  constructor(stack: GitHubStack, id: string);

  // Generated methods for each action
  checkout(name: string, inputs?: CheckoutInputs): ActionConstruct;
  setupNode(name: string, inputs?: SetupNodeInputs): ActionConstruct;
  // ... other actions
}

ActionConstruct

Base class for all action wrappers.

class ActionConstruct {
  constructor(name: string, inputs?: Record<string, any>);

  toStep(): Step;
  withInputs(inputs: Record<string, any>): ActionConstruct;
}

Step

Represents a workflow step.

interface Step {
  name: string;
  uses?: string;
  with?: Record<string, any>;
  run?: string;
  shell?: string;
  env?: Record<string, string>;
  if?: string;
  continueOnError?: boolean;
  timeoutMinutes?: number;
}

Utility Functions

createStep

Creates a custom step.

function createStep(
  name: string,
  run: string,
  options?: {
    shell?: string;
    env?: Record<string, string>;
    if?: string;
    continueOnError?: boolean;
    timeoutMinutes?: number;
  }
): Step;

run

Creates a run step.

function run(
  name: string,
  command: string,
  options?: {
    shell?: string;
    env?: Record<string, string>;
    if?: string;
    continueOnError?: boolean;
    timeoutMinutes?: number;
  }
): Step;

SharedWorkflowConstruct

Creates reusable workflow definitions.

class SharedWorkflowConstruct {
  constructor(stack: GitHubStack, id: string, props: SharedWorkflowProps);
}

SharedWorkflowProps

interface SharedWorkflowProps {
  name: string;
  description?: string;
  inputs?: Record<string, WorkflowInput>;
  outputs?: Record<string, WorkflowOutput>;
  secrets?: Record<string, WorkflowSecret>;
  jobs: Record<string, JobDefinition>;
}

Configuration Types

DotGithubConfig

Main configuration interface.

interface DotGithubConfig {
  version: string;
  rootDir: string;
  outputDir: string;
  actions: DotGithubAction[];
  constructs: ConstructConfig[];
  stacks: StackConfig[];
  options?: DotGithubOptions;
  pins?: PinsConfig;
}

DotGithubAction

Action configuration.

interface DotGithubAction {
  orgRepo: string;
  ref: string;
  versionRef: string;
  actionName: string;
  outputPath: string;
  actionPath?: string;
  generateCode?: boolean;
}

ConstructConfig

Construct configuration.

interface ConstructConfig {
  name: string;
  package: string;
  config: Record<string, any>;
  enabled: boolean;
}

StackConfig

Stack configuration.

interface StackConfig {
  name: string;
  constructs: string[];
  config: Record<string, any>;
}

PinsConfig

Action pinning configuration.

interface PinsConfig {
  constructs?: Record<string, Record<string, string>>;
  stacks?: Record<string, Record<string, string>>;
}

Input/Output Types

GitHubWorkflowInput

interface GitHubWorkflowInput {
  description: string;
  required?: boolean;
  default?: string | number | boolean;
  type?: 'string' | 'number' | 'boolean';
}

GitHubWorkflowOutput

interface GitHubWorkflowOutput {
  description: string;
  value: string;
}

GitHubWorkflowSecret

interface GitHubWorkflowSecret {
  description: string;
  required?: boolean;
}

Action Input Types

CheckoutInputs

interface CheckoutInputs {
  repository?: string;
  ref?: string;
  token?: string;
  'ssh-key'?: string;
  'ssh-known-hosts'?: string;
  'ssh-strict'?: boolean;
  'persist-credentials'?: boolean;
  path?: string;
  clean?: boolean;
  'fetch-depth'?: number;
  lfs?: boolean;
  submodules?: boolean | 'recursive';
  'set-safe-directory'?: boolean;
}

SetupNodeInputs

interface SetupNodeInputs {
  'node-version'?: string;
  'node-version-file'?: string;
  cache?: string;
  'cache-dependency-path'?: string;
  'check-latest'?: boolean;
  'always-auth'?: boolean;
  'registry-url'?: string;
  scope?: string;
  token?: string;
}

SetupPythonInputs

interface SetupPythonInputs {
  'python-version'?: string;
  'python-version-file'?: string;
  cache?: string;
  'cache-dependency-path'?: string;
  token?: string;
  architecture?: string;
  'update-environment'?: boolean;
}

Error Handling

ValidationError

Thrown when configuration validation fails.

class ValidationError extends Error {
  constructor(message: string, details?: any);
}

SynthesisError

Thrown when workflow synthesis fails.

class SynthesisError extends Error {
  constructor(message: string, details?: any);
}

Type Guards

isGitHubConstruct

function isGitHubConstruct(obj: any): obj is GitHubConstruct;

isWorkflowConstruct

function isWorkflowConstruct(obj: any): obj is WorkflowConstruct;

isJobConstruct

function isJobConstruct(obj: any): obj is JobConstruct;

Constants

Default Values

const DEFAULT_NODE_VERSION = '18';
const DEFAULT_PYTHON_VERSION = '3.10';
const DEFAULT_RUNNER = 'ubuntu-latest';

Supported Runners

const SUPPORTED_RUNNERS = [
  'ubuntu-latest',
  'ubuntu-22.04',
  'ubuntu-20.04',
  'windows-latest',
  'windows-2022',
  'macos-latest',
  'macos-13',
  'macos-12',
];

Examples

Basic Construct

import {
  GitHubConstruct,
  GitHubStack,
  WorkflowConstruct,
  JobConstruct,
} from '@dotgithub/core';

export class BasicConstruct extends GitHubConstruct {
  readonly name = 'basic-construct';
  readonly version = '1.0.0';
  readonly description = 'A basic construct example';

  validate(stack: GitHubStack): void {
    // No validation needed
  }

  describe() {
    return {
      name: this.name,
      version: this.version,
      description: this.description,
    };
  }

  async synthesize(stack: GitHubStack): Promise<void> {
    const wf = new WorkflowConstruct(stack, 'ci', {
      name: 'CI Workflow',
      on: { push: { branches: ['main'] } },
      jobs: {},
    });

    new JobConstruct(wf, 'test', {
      'runs-on': 'ubuntu-latest',
      steps: [
        {
          name: 'Checkout',
          uses: 'actions/checkout@v4',
        },
        {
          name: 'Run tests',
          run: 'npm test',
        },
      ],
    });
  }
}

export default new BasicConstruct();

Advanced Construct with Configuration

import { z } from 'zod';
import {
  GitHubConstruct,
  GitHubStack,
  WorkflowConstruct,
  JobConstruct,
  Actions,
} from '@dotgithub/core';

export class AdvancedConstruct extends GitHubConstruct {
  readonly name = 'advanced-construct';
  readonly version = '1.0.0';
  readonly description = 'An advanced construct with configuration';

  private readonly configSchema = z.object({
    environment: z.enum(['development', 'staging', 'production']),
    nodeVersion: z.string().default('18'),
    testCommand: z.string().default('npm test'),
    deployCommand: z.string().default('npm run deploy'),
  });

  validate(stack: GitHubStack): void {
    this.configSchema.parse(stack.config);
  }

  describe() {
    return {
      name: this.name,
      version: this.version,
      description: this.description,
      configSchema: this.configSchema,
    };
  }

  async synthesize(stack: GitHubStack): Promise<void> {
    const config = this.configSchema.parse(stack.config);
    const { checkout, setupNode } = new Actions(stack, 'actions');

    const wf = new WorkflowConstruct(stack, 'ci', {
      name: 'CI/CD Workflow',
      on: {
        push: { branches: ['main'] },
        pull_request: {},
      },
      jobs: {},
    });

    // Test job
    new JobConstruct(wf, 'test', {
      'runs-on': 'ubuntu-latest',
      steps: [
        checkout('Checkout code').toStep(),
        setupNode('Setup Node.js', {
          'node-version': config.nodeVersion,
        }).toStep(),
        {
          name: 'Install dependencies',
          run: 'npm install',
        },
        {
          name: 'Run tests',
          run: config.testCommand,
        },
      ],
    });

    // Deploy job (only on main branch)
    if (config.environment === 'production') {
      new JobConstruct(wf, 'deploy', {
        'runs-on': 'ubuntu-latest',
        needs: ['test'],
        if: "github.ref == 'refs/heads/main'",
        steps: [
          checkout('Checkout code').toStep(),
          setupNode('Setup Node.js', {
            'node-version': config.nodeVersion,
          }).toStep(),
          {
            name: 'Deploy',
            run: config.deployCommand,
            env: {
              NODE_ENV: config.environment,
            },
          },
        ],
      });
    }
  }
}

export default new AdvancedConstruct();

FilesExpand file tree

api-reference.md

Latest commit

History