@happyvertical/github-actions

GitHub Actions utilities for CI/CD automation. Provides AI-powered issue triage (labeling, duplicate detection, project board management), implementation planning with Definition of Ready validation, and standardized label management. Uses @happyvertical/repos and @happyvertical/projects for GitHub API interactions.

Installation

npm install @happyvertical/github-actions

Peer dependencies: @happyvertical/repos, @happyvertical/projects.

CLI Usage

The package provides two CLI commands:

Triage

Run AI-powered issue triage in a GitHub Actions workflow:

# Required env vars: GITHUB_TOKEN, GITHUB_REPOSITORY, ISSUE_NUMBER, ISSUE_TITLE, ISSUE_AUTHOR
# Optional: ISSUE_BODY, CONFIG (path to config file or JSON string)
npx @happyvertical/github-actions triage

Labels

Apply standardized labels (type, priority, size, status, agent) to a repository:

github-actions labels --owner happyvertical --repo sdk --dry-run
github-actions labels --owner happyvertical --repo sdk --include-area --area core --area api

Configuration

Create a .github/triage-config.json:

{
  "repoDescription": "TypeScript monorepo for AI agent development",
  "packagePattern": "@happyvertical/*",
  "packageExamples": ["@happyvertical/ai", "@happyvertical/sql"],
  "projectEnabled": true,
  "projectId": "PVT_kwDOB9Y8ns4A8-TY",
  "statusFieldId": "PVTSSF_lADOB9Y8ns4A8-TYzgw0GaY",
  "statusOptions": {
    "To Do": "c0c9ab27",
    "In Progress": "ce670088",
    "Review & Testing": "ee1f96bd"
  }
}

Field	Type	Required	Description
repoDescription	string	Yes	Brief description for AI context
packagePattern	string	No	Monorepo package pattern (e.g., @happyvertical/*)
packageExamples	string[]	No	Example package names for AI guidance
projectEnabled	boolean	No	Enable GitHub Projects V2 integration
projectId	string	If project	Project V2 ID
statusFieldId	string	If project	Status field ID
statusOptions	object	If project	Status name to option ID mapping

Programmatic API

Issue Triage

import { triageIssue } from '@happyvertical/github-actions';

const result = await triageIssue({
  token: process.env.GITHUB_TOKEN!,
  owner: 'happyvertical',
  repo: 'sdk',
  issueNumber: 123,
  issueTitle: 'Add Redis cache support',
  issueBody: 'We need distributed caching...',
  issueAuthor: 'username',
  config: {
    repoDescription: 'TypeScript monorepo for AI agent development',
    packagePattern: '@happyvertical/*',
    projectEnabled: false,
  },
});

Triage analyzes the issue with AI (GitHub Models API), applies type/priority/size labels, searches for duplicates, posts a structured comment, and optionally updates the project board.

Planning

import { startPlanning, completePlanning } from '@happyvertical/github-actions';

// Generate an AI implementation plan and post it as a comment
const planResult = await startPlanning(context);

// Validate Definition of Ready and move to Ready status
const completeResult = await completePlanning(context);

Label Management

import {
  getAllStandardLabels,
  getLabelsByCategory,
  migrateLabel,
} from '@happyvertical/github-actions';

const allLabels = getAllStandardLabels(); // type, priority, size, status, agent
const bugLabels = getLabelsByCategory('type');
const newName = migrateLabel('enhancement'); // → 'type: feature'

Shared Utilities

import {
  createRepository,
  createProject,
  getAICompletion,
  parseAIJson,
} from '@happyvertical/github-actions';

// Adapter factories for @happyvertical/repos and @happyvertical/projects
const repo = await createRepository(token, 'happyvertical', 'sdk');
const project = await createProject(token, projectId, statusFieldId, statusOptions);

// AI completion with auto-provider selection (GitHub Models → OpenAI → Anthropic)
const response = await getAICompletion([
  { role: 'system', content: 'You are a helpful assistant.' },
  { role: 'user', content: 'Analyze this issue...' },
]);

Architecture

• triage/ — Issue triage: AI analysis, labeling, duplicate detection, project board updates
• planning/ — Implementation planning: AI plan generation, Definition of Ready validation
• shared/ — AI client (GitHub Models, OpenAI, Anthropic), GitHub API helpers, label definitions, project utilities, adapter factories
• cli.ts — CLI entry point (triage, labels commands)

License

MIT