CI/CD Workflows

This directory contains GitHub Actions workflows for the uniswap-ai repository. The workflows are designed to validate PRs, automate code reviews, and publish packages.

Workflow Overview

Workflow	Trigger	Purpose
PR Checks	PR events	Build, lint, test, validate plugins & skills
Check PR Title	PR events	Enforce conventional commit format
Claude Code Review	PR events, comments	AI-powered code review
Claude Docs Check	PR events	Validate documentation updates
Generate PR Title & Description	PR events	Auto-generate PR metadata
Generate Documentation	Push to main, manual	Auto-generate API documentation
Publish Packages	Push to main, manual	Publish npm packages
Evals	PR events, manual	LLM evaluation of AI skills
GitHub Actions Analysis	Push to main, PRs	Security analysis & syntax validation

Workflows

PR Checks

File: ci-pr-checks.yml

Core CI validation workflow that runs on all PRs:

• Validates bun.lock is in sync via bun install --frozen-lockfile
• Builds affected packages with Nx
• Runs linting and formatting checks
• Lints documentation prose with Vale (non-blocking)
• Executes test suites with coverage
• Validates plugin configurations
• Validates skills (frontmatter, consistency with plugin.json)
• Validates documentation pages exist for all plugins and skills

Automated PRs (dependabot, releases) may skip certain checks.

Check PR Title

File: ci-check-pr-title.yml

Enforces conventional commit format for PR titles using semantic-pull-request. Requires scope (e.g., feat(hooks):, fix(ci):).

Claude Code Review

File: claude-code-review.yml

AI-powered code review using Claude:

• Provides formal GitHub reviews (APPROVE/REQUEST_CHANGES/COMMENT)
• Posts inline comments on specific lines
• Auto-resolves fixed issues on subsequent reviews
• Uses patch-ID caching to avoid duplicate reviews on rebases

Triggering a new review:

• Add a comment containing @request-claude-review
• Use workflow_dispatch: gh workflow run "Claude Code Review" -f pr_number=123

Claude Docs Check

File: claude-docs-check.yml

Validates that PR documentation is properly updated:

• Checks CLAUDE.md files are updated when code in their scope changes
• Verifies README.md files reflect current state
• Ensures plugin versions are bumped when plugin code changes

Uses a shared reusable workflow.

Generate PR Title & Description

File: generate-pr-title-description.yml

Auto-generates PR titles and descriptions using Claude:

• Creates conventional commit-style titles based on repository patterns
• Generates comprehensive descriptions from merged PR templates
• Skips rebases using patch-ID detection

Generate Documentation

File: generate-docs.yml

Automatically generates API documentation using TypeDoc:

• Triggers on push to main when TypeScript files in evals/framework/** or packages/** change
• Also accepts typedoc.json changes and manual workflow_dispatch triggers
• Runs bunx nx run docs:generate-api-docs to generate documentation
• Auto-commits generated docs to docs/api/** with [skip ci] flag
• Skips execution if commit message starts with docs: auto-generate to prevent loops
• Uses concurrency controls to prevent overlapping doc generation

Deploy Documentation

Documentation is deployed via Vercel (not GitHub Actions). Vercel's GitHub integration automatically:

• Deploys to production on push to main when docs/ changes
• Creates preview deployments for every PR
• Build command: bunx nx run docs:build

Configuration is in vercel.json at the repo root.

Publish Packages

File: publish-packages.yml

Handles npm package publishing:

• Auto mode (push to main): Detects affected packages, publishes with latest tag
• Force mode (manual): Publishes specified packages with next tag and prerelease versions

Evals

File: evals.yml

LLM-based evaluation of AI skills using Promptfoo:

• Runs on PRs that modify packages/plugins/**, evals/**, or evals.yml
• Per-suite Nx projects: Each eval suite is its own Nx project (eval-suite-<name>) with implicitDependencies on its corresponding plugin and the evals project
• Uses nx affected -t eval to run only suites whose plugin or eval dependencies changed
• Nx compares suite inputs (config, cases, rubrics, skill files, and shared eval infra) against its cache
• If inputs haven't changed, Nx restores the cached results.json without making LLM API calls
• Persistent Nx cache: Uses split cache/restore + cache/save (with if: always()) so cache is preserved even when the job fails
• Aggregates pass/fail across affected suites; requires ≥85% pass rate
• Manual trigger supports: specific suite (nx run eval-suite-<name>:eval), skip cache, multi-model mode

GitHub Actions Analysis

File: zizmor.yml

Validates GitHub Actions workflows for security and syntax correctness:

• zizmor: Static security analysis using zizmor — scans for template injection, credential leakage, permission scope issues
• actionlint: Syntax validation using actionlint — catches YAML syntax errors, invalid event types, type errors, and expression issues
• Runs on push to main and all PRs
• Reports findings as GitHub annotations on PRs

Required Secrets

Secret	Purpose	Required By
ANTHROPIC_API_KEY	Anthropic API authentication	Evals
CLAUDE_CODE_OAUTH_TOKEN	Claude AI authentication	Code Review, Docs Check, PR Metadata, Evals
WORKFLOW_PAT	Push commits/tags, branch creation	Docs Check, PR Metadata, Publish
SERVICE_ACCOUNT_GPG_PRIVATE_KEY	Signing commits/tags	Publish

npm publish authentication uses Trusted Publishing (OIDC) via id-token: write — no NPM_TOKEN / NODE_AUTH_TOKEN secret is required. Configure a Trusted Publisher on npmjs.com mapping each package to publish-packages.yml and the Production environment before its first publish.

Repository Variables

Variable	Purpose
NODE_VERSION	Node.js version for CI (22.x)
NPM_VERSION	npm version for the publish job (11.7.0+, OIDC support)
BUN_VERSION	Bun version for CI (defaults to 1.3.13)

Security

All workflows follow security best practices:

• External actions are pinned to specific commit SHAs
• Bullfrog security scanning on all jobs
• Concurrency groups prevent duplicate runs
• Minimal required permissions per job

Shared Workflows

Several workflows use external reusable workflows:

• _claude-docs-check.yml - Documentation validation
• _generate-pr-metadata.yml - PR title/description generation
• _claude-code-review.yml - Code review logic