CI/CD Integration

Why CI/CD Integration?

Running Fulcrum manually is great for development. Running Fulcrum in CI/CD is where it scales. Every pull request can get automated code review, quality gates can enforce standards, and PR descriptions can be generated automatically.

When to Use Fulcrum in CI/CD

Great Use Cases

• Automated code review: Every PR gets reviewed for issues
• Quality gate enforcement: Block merges that don't meet standards
• PR description generation: Auto-generate comprehensive PR summaries
• Documentation updates: Verify docs match code changes
• Security scanning: Check for common vulnerabilities
• Migration assistance: Validate database migrations

Less Suitable Use Cases

• Complex multi-step tasks: Better done interactively
• Tasks requiring human judgment: Design decisions, architecture
• Long-running operations: CI has time limits

GitHub Actions Workflows

Basic Code Review Workflow

# .github/workflows/fulcrum-review.yml
name: Fulcrum Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  code-review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for diff

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Fulcrum
        run: npm install -g @anthropic/fulcrum-cli

      - name: Run Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          fulcrum review \
            --pr ${{ github.event.pull_request.number }} \
            --repo ${{ github.repository }} \
            --post-comment

Comprehensive CI Pipeline

# .github/workflows/fulcrum-ci.yml
name: Fulcrum CI Pipeline

on:
  pull_request:
    types: [opened, synchronize, reopened]
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: write
  issues: write

env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

jobs:
  # Quick checks that run on every push
  lint-and-typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck

  # Fulcrum code review on PRs only
  fulcrum-review:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    needs: [lint-and-typecheck]
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Fulcrum
        run: npm install -g @anthropic/fulcrum-cli

      - name: Fetch PR diff
        run: |
          git fetch origin ${{ github.base_ref }}
          git diff origin/${{ github.base_ref }}...HEAD > pr.diff

      - name: Run Fulcrum Review
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          fulcrum review \
            --diff pr.diff \
            --context agent_docs/ \
            --output review.md

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: review
            });

  # Quality gate check
  quality-gate:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    needs: [fulcrum-review]
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Fulcrum
        run: npm install -g @anthropic/fulcrum-cli

      - name: Run Quality Gate
        run: |
          fulcrum quality-gate \
            --checks security,performance,testing \
            --fail-on critical

  # Generate PR description
  pr-description:
    if: github.event_name == 'pull_request' && github.event.action == 'opened'
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Fulcrum
        run: npm install -g @anthropic/fulcrum-cli

      - name: Generate Description
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          fulcrum pr-describe \
            --pr ${{ github.event.pull_request.number }} \
            --repo ${{ github.repository }} \
            --update

Automated Code Review in PRs

The code review workflow analyzes your PR and posts findings as a comment:

## 🔍 Fulcrum Code Review

### Summary
This PR adds user notification preferences with email and in-app options.
Changes span frontend components, backend API, and database schema.

### Findings

#### 🔴 Critical
- **SQL Injection Risk** (src/api/notifications.ts:45)
  User input passed directly to query. Use parameterized queries.

#### 🟡 Important  
- **Missing Error Handling** (src/services/email.ts:23)
  SendGrid API call has no try/catch. Add error handling.

- **N+1 Query** (src/api/notifications.ts:67)
  Loop queries user for each notification. Use JOIN or batch.

#### 🔵 Suggestions
- Consider adding index on notifications.user_id
- NotificationBell component could use React.memo

### Verdict
**Changes Requested** - Please address critical and important findings.

Quality Gates in CI

Quality gates enforce standards before code can be merged:

# Run specific quality checks
fulcrum quality-gate --checks security,performance,testing

# Fail on critical issues only
fulcrum quality-gate --fail-on critical

# Fail on critical or important issues
fulcrum quality-gate --fail-on important

# Custom threshold
fulcrum quality-gate --max-critical 0 --max-important 3

Available Quality Checks

Branch Protection Rules

# Recommended branch protection for main branch

Required status checks:
✓ lint-and-typecheck
✓ fulcrum-review
✓ quality-gate

Settings:
✓ Require branches to be up to date
✓ Require conversation resolution
✓ Require review from code owners

Agent-Generated PR Descriptions

Fulcrum can generate comprehensive PR descriptions automatically:

## What Changed
Added user notification preferences feature allowing users to configure
their email and in-app notification settings.

## Why
Users requested granular control over notifications (see #234).
Currently all users receive all notifications with no opt-out.

## Changes

### Database
- Added `notification_preferences` table with user_id FK
- Added `notification_type` enum for email/in_app/push

### Backend
- New NotificationPreferencesService with CRUD operations
- API endpoints: GET/PUT /api/users/:id/notification-preferences
- Integration with existing NotificationService

### Frontend
- NotificationPreferences component in user settings
- Toggle controls for each notification category
- Real-time preference updates via API

## Testing
- Unit tests for NotificationPreferencesService (12 tests)
- API integration tests (8 tests)
- E2E test for preferences flow (1 test)

## Migration
Run `npm run migrate` to apply database changes.
Backward compatible - existing users get all notifications enabled.

## Screenshots
[Auto-attached if changed files include UI components]

GitLab CI Configuration

# .gitlab-ci.yml
stages:
  - lint
  - review
  - quality

variables:
  ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY

lint:
  stage: lint
  script:
    - npm ci
    - npm run lint
    - npm run typecheck

fulcrum-review:
  stage: review
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - npm install -g @anthropic/fulcrum-cli
    - git fetch origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
    - git diff origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD > mr.diff
    - fulcrum review --diff mr.diff --output review.md
  artifacts:
    paths:
      - review.md

quality-gate:
  stage: quality
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - npm install -g @anthropic/fulcrum-cli
    - fulcrum quality-gate --checks security,performance --fail-on critical

CircleCI Configuration

# .circleci/config.yml
version: 2.1

jobs:
  lint:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - restore_cache:
          keys:
            - npm-deps-{{ checksum "package-lock.json" }}
      - run: npm ci
      - save_cache:
          key: npm-deps-{{ checksum "package-lock.json" }}
          paths:
            - node_modules
      - run: npm run lint
      - run: npm run typecheck

  fulcrum-review:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run: npm install -g @anthropic/fulcrum-cli
      - run: |
          fulcrum review \
            --diff <(git diff origin/main...HEAD) \
            --output review.md
      - store_artifacts:
          path: review.md

workflows:
  ci:
    jobs:
      - lint
      - fulcrum-review:
          requires:
            - lint
          filters:
            branches:
              ignore: main

Best Practices

Secrets Management

Caching

# Cache Fulcrum installation for faster runs
- name: Cache Fulcrum
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: fulcrum-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}

Timeout Configuration

# Set appropriate timeouts for Fulcrum jobs
jobs:
  fulcrum-review:
    runs-on: ubuntu-latest
    timeout-minutes: 15  # Generous timeout for review
    steps:
      # ...

Conditional Runs

# Skip review for certain paths
- name: Check for code changes
  id: changes
  run: |
    if git diff --name-only origin/main...HEAD | grep -qE '\.(ts|tsx|js|jsx)$'; then
      echo "has_code_changes=true" >> $GITHUB_OUTPUT
    fi

- name: Run Fulcrum Review
  if: steps.changes.outputs.has_code_changes == 'true'
  run: fulcrum review ...

Troubleshooting

Common Issues

Debug Mode

# Enable verbose logging for debugging
fulcrum review --verbose --debug

# Output includes:
# - Files being analyzed
# - Memory Bank files loaded
# - API request/response timing
# - Quality check details

Next Steps

You've set up CI/CD integration. For a complete reference of all Fulcrum commands and their options, see the Commands Reference.