GitHub Actions Integration Setup Guide

Complete guide to integrating SpecWeave with GitHub Actions for automated spec-driven development

Overview
Prerequisites
Quick Start
Workflow Tiers
Configuration
Authentication Setup
Workflow Features
Testing Your Setup
Troubleshooting
Advanced Configuration

Overview

SpecWeave GitHub Actions integration brings automated spec-driven development to your GitHub repositories. When enabled, the system:

✅ Auto-generates increment structures from issues (spec/plan/tasks/tests)
✅ Validates PRs against specifications (spec alignment, test coverage)
✅ Prevents regressions (brownfield protection - requires docs before modifications)
✅ Auto-updates documentation (CLAUDE.md, API docs, changelog)
✅ Enforces test coverage (TC-0001 traceability, skill tests, E2E tests)
✅ Scans for security (vulnerabilities, code security, compliance)
✅ Detects performance regressions (compare baseline vs PR)
✅ Syncs external systems (JIRA, Slack, Azure DevOps)

Result: 93% time savings with zero spec drift and zero regressions.

Prerequisites

Required

GitHub Repository with SpecWeave initialized
- .specweave/config.yaml exists
- CLAUDE.md exists
- docs/internal/strategy/ folder exists
Anthropic API Key
- Sign up at https://console.anthropic.com/
- Create API key with Claude access
- Store as GitHub secret
GitHub Token (automatically provided)
- No setup needed
- Auto-available as GITHUB_TOKEN

Optional (for advanced features)

JIRA Account + API token (for JIRA sync)
Slack Webhook (for notifications)
Azure DevOps + PAT (for ADO sync)

Quick Start

Step 1: Choose Your Workflow Tier

SpecWeave provides 3 workflow tiers:

Tier	File	Features	Best For
Starter	`specweave-starter.yml`	Feature planning, basic PR validation, auto-docs	New users, small teams
Standard	`specweave-standard.yml`	+ Brownfield protection, test coverage, issue triage	Production teams
Enterprise	`specweave-enterprise.yml`	+ Security scanning, performance, compliance	Large organizations

Recommendation: Start with Starter, upgrade to Standard after testing.

Step 2: Add Anthropic API Key to GitHub Secrets

Go to your repository on GitHub
Navigate to: Settings → Secrets and variables → Actions
Click New repository secret
Name: ANTHROPIC_API_KEY
Value: Your Anthropic API key (starts with sk-ant-)
Click Add secret

Step 3: Enable Workflow

Option A: Copy from templates (if SpecWeave installed)

# Copy starter workflow
cp .github/workflows/specweave-starter.yml.template .github/workflows/specweave-starter.yml

# Or use install script
./install.sh --enable-github-actions

Option B: Already in repository (workflows are committed)

The workflows are already in .github/workflows/ - just ensure API key is set!

Step 4: Test the Integration

Create a test issue:

Go to Issues → New issue
Title: "Add user authentication"
Add label: feature
Submit

Expected behavior:

GitHub Action triggers
Feature structure auto-generated in features/0001-user-authentication/
Branch created: feature/0001-user-authentication
Draft PR created
Comment posted on issue with PR link

Time: ~2-3 minutes

Workflow Tiers

Tier 1: Starter (Recommended for New Users)

File: .github/workflows/specweave-starter.yml

Features:

✅ Auto increment planning (issue labeled 'feature')
✅ Basic PR validation (spec existence, alignment)
✅ Auto-documentation updates (on merge)

Triggers:

Issues: labeled
PRs: opened, synchronize
Push: main, features/**

Estimated cost: ~$0.50/PR (with 1000 tokens per run)

Setup time: 5 minutes

Tier 2: Standard (Recommended for Production)

File: .github/workflows/specweave-standard.yml

Features:

✅ Everything in Starter, PLUS:
✅ Intelligent issue triage (auto-label, prioritize, assign)
✅ Brownfield protection (blocks modifications without docs)
✅ Test coverage validation (TC-0001 traceability)
✅ External integrations (JIRA, Slack, ADO)

Triggers:

Issues: opened, labeled
PRs: opened, synchronize, reopened
Push: main, develop, features/**

Estimated cost: ~$1.50/PR (with 3000 tokens per run)

Setup time: 15 minutes

Additional secrets needed:

JIRA_TOKEN (optional)
SLACK_WEBHOOK (optional)

Tier 3: Enterprise (For Large Organizations)

File: .github/workflows/specweave-enterprise.yml

Features:

✅ Everything in Standard, PLUS:
✅ Security vulnerability scanning
✅ Performance regression detection
✅ Compliance validation (GDPR, HIPAA, SOC 2)
✅ Advanced analytics and reporting
✅ Scheduled security scans

Triggers:

Issues: opened, labeled, assigned
PRs: opened, synchronize, reopened, ready_for_review
PR Reviews: submitted
Push: main, develop, release/**
Schedule: Daily at 2 AM UTC (security scans)

Estimated cost: ~$3.00/PR (with 6000 tokens per run)

Setup time: 30 minutes

Additional secrets needed:

All from Standard, PLUS:
AZURE_DEVOPS_TOKEN (optional)
Performance testing setup

Configuration

.specweave/config.yaml

Add GitHub Actions configuration to your .specweave/config.yaml:

# SpecWeave Configuration
name: "my-project"
version: "1.0.0"

# GitHub Actions Integration
github_actions:
  enabled: true
  tier: "standard"  # starter | standard | enterprise

  # Feature planning
  feature_planning:
    enabled: true
    auto_create_pr: true
    draft_pr: true

  # PR validation
  pr_validation:
    enabled: true
    require_spec: true
    require_tests: true
    minimum_coverage: 80  # percent

  # Brownfield protection
  brownfield:
    enabled: true
    block_without_docs: true
    block_without_tests: true

  # Test coverage
  test_coverage:
    enabled: true
    require_tc_traceability: true
    minimum_skill_tests: 3
    require_e2e_for_ui: true

  # Documentation
  auto_docs:
    enabled: true
    update_claude_md: true
    update_api_docs: true
    update_changelog: true

  # External integrations
  integrations:
    jira:
      enabled: false
      url: "https://your-domain.atlassian.net"
      project_key: "PROJ"

    slack:
      enabled: false
      webhook_url: "${SLACK_WEBHOOK}"
      channel: "#specweave-notifications"

    azure_devops:
      enabled: false
      organization: "your-org"
      project: "your-project"

  # Enterprise features
  enterprise:
    security_scanning:
      enabled: false
      block_on_critical: true
      block_on_high: false

    performance:
      enabled: false
      regression_threshold: 10  # percent slower
      block_on_critical_regression: true

    compliance:
      enabled: false
      frameworks:
        - gdpr
        - hipaa
        - soc2

# AI Model Configuration
ai:
  model: "claude-sonnet-4-5-20250929"
  max_tokens: 16000

Authentication Setup

Anthropic API (Required)

Get API Key:

Visit https://console.anthropic.com/
Sign up or log in
Go to API Keys
Create new key
Copy key (starts with sk-ant-)

Add to GitHub:

Repository → Settings → Secrets and variables → Actions
New repository secret
Name: ANTHROPIC_API_KEY
Value: Your API key
Add secret

Cost: Pay-per-use

Sonnet: $3 per million input tokens, $15 per million output tokens
Estimated: $1-3 per PR depending on tier

JIRA Integration (Optional)

Get JIRA Token:

Log into JIRA
Go to Account Settings → Security → API Tokens
Create API token
Copy token

Add to GitHub:

Repository → Settings → Secrets
Name: JIRA_TOKEN
Value: Your JIRA token

Update config.yaml:

integrations:
  jira:
    enabled: true
    url: "https://your-domain.atlassian.net"
    project_key: "PROJ"

Slack Integration (Optional)

Get Webhook URL:

Go to https://api.slack.com/apps
Create app or select existing
Incoming Webhooks → Activate
Add New Webhook to Workspace
Select channel
Copy webhook URL

Add to GitHub:

Repository → Settings → Secrets
Name: SLACK_WEBHOOK
Value: Webhook URL

Update config.yaml:

integrations:
  slack:
    enabled: true
    channel: "#specweave-notifications"

Azure DevOps Integration (Optional)

Get PAT (Personal Access Token):

Azure DevOps → User Settings → Personal Access Tokens
New Token
Scopes: Work Items (Read, Write), Code (Read)
Copy token

Add to GitHub:

Repository → Settings → Secrets
Name: AZURE_DEVOPS_TOKEN
Value: Your PAT

Update config.yaml:

integrations:
  azure_devops:
    enabled: true
    organization: "your-org"
    project: "your-project"

Workflow Features

1. Auto Increment Planning

Trigger: Issue labeled with feature

What it does:

Reads issue title and description
Activates feature-planner skill
Generates complete increment structure:
- .specweave/increments/00001-feature-name/spec.md
- .specweave/increments/00001-feature-name/plan.md
- .specweave/increments/00001-feature-name/tasks.md
- .specweave/increments/00001-feature-name/tests.md
- .specweave/increments/00001-feature-name/context-manifest.yaml
Creates branch feature/0001-feature-name
Commits files
Creates draft PR
Comments on issue with PR link

Time saved: 2 hours → 5 minutes (96%)

Example:

Issue: "Add user authentication with OAuth2"
Label: feature

→ Auto-generates:
  features/0003-user-authentication/
  ├── spec.md (WHAT/WHY)
  ├── plan.md (HOW)
  ├── tasks.md (checklist)
  ├── tests.md (TC-0001 through TC-0010)
  └── context-manifest.yaml

→ Creates: PR #15 (draft)
→ Comments: "Feature structure created! Review PR #15"

2. Spec-Aware PR Review

Trigger: PR opened or updated

What it does:

Loads feature's context-manifest.yaml
Loads referenced specs from docs/internal/strategy/
Validates:
- ✅ Spec exists for changes
- ✅ Code aligns with spec
- ✅ Test coverage (TC-0001 traceability)
- ✅ Skills have ≥3 test cases
- ✅ ADRs for architecture changes
Posts review comment with findings
Approves, requests changes, or blocks

Time saved: 30 minutes → 2 minutes (93%)

Example:

## SpecWeave Validation Report

### ✅ Passed Checks
- Spec exists: docs/internal/strategy/auth/oauth-spec.md
- Test coverage: 100% (TC-0001 through TC-0010 covered)
- ADR exists: .specweave/docs/decisions/005-oauth-strategy.md

### ⚠️ Warnings
- Performance: New database queries (review indexing)

### ❌ Required Changes
- Missing skill tests: src/skills/oauth-handler/ has only 2 tests (need 3)

**Status**: ⚠️ Changes Required

3. Brownfield Protection

Trigger: PR modifies existing code (src/**/*.ts)

What it does:

Detects modifications to existing files
Checks for documentation:
- Specs in docs/internal/strategy/
- Tests in tests/
- Architecture docs
If missing:
- ❌ BLOCKS PR
- Posts detailed requirements
- Provides remediation steps

Prevents: 100% of regressions from undocumented changes

Example:

## 🚨 Brownfield Modification Detected

### Modified Files
- src/services/payment-processor.ts (146 lines changed)

### Missing Documentation
- ❌ No spec for payment-processor
- ❌ No tests for current behavior

### Required Actions
1. Document current behavior:
   - Create docs/internal/strategy/payments/existing-flow.md
2. Create regression tests:
   - Add E2E tests for current payment flow
3. Get user approval

**PR Status**: ⏸️ Blocked

4. Test Coverage Validation

Trigger: PR opened or updated

What it does:

Runs test suite with coverage
Validates:
- TC-0001 traceability (spec → tests)
- Skills have ≥3 test cases
- E2E tests for UI changes
- Coverage >80% for critical paths
Posts coverage report
Blocks if requirements not met

Example:

## Test Coverage Report

### ✅ TC-0001 Traceability
- TC-0001: Covered in tests/e2e/login.spec.ts
- TC-0002: Covered in tests/e2e/login.spec.ts
- TC-0003: Covered in tests/unit/validation.test.ts

### Skill Tests
✅ oauth-handler: 5 test cases

### Coverage Metrics
- Overall: 87% ✅
- Changed Files: 92% ✅
- Critical Paths: 95% ✅

**Status**: ✅ Passed

5. Auto-Documentation Updates

Trigger: PR merged to main

What it does:

Compares HEAD with HEAD~1
Identifies changes:
- Structure changes
- CLI changes
- Skills API changes
- Feature completion
Updates relevant docs:
- CLAUDE.md (if structure changed)
- .specweave/docs/api/ (if API changed)
- .specweave/docs/changelog/ (always)
Commits changes with message: "docs: auto-update after merge"
Syncs with JIRA/Slack if configured

Time saved: 1 hour → 0 minutes (100%)

6. Security Scanning (Enterprise)

Trigger: PR opened or daily schedule

What it does:

Runs npm audit
Analyzes code for security issues:
- SQL injection
- XSS vulnerabilities
- Secret leaks
- Authentication issues
Posts security report
Blocks if critical vulnerabilities

Example:

## 🔒 Security Scan Report

### Critical Issues
None ✅

### High Priority
- lodash: Prototype Pollution (CVE-2020-8203)
  Fix: Update to lodash@4.17.21

### Recommendations
- Enable rate limiting on login endpoint
- Add CSRF protection for forms

**Status**: ⚠️ Review Needed

7. Performance Regression (Enterprise)

Trigger: PR opened

What it does:

Runs performance tests on PR
Runs same tests on base branch
Compares results
Identifies regressions (>10% slower)
Posts performance report
Blocks if critical regression (>25% slower)

Example:

## ⚡ Performance Analysis

### Regression Detected
- API /users/list: 15% slower (250ms → 287ms)
  Cause: N+1 query detected

### Improvements
- API /posts/create: 20% faster (cache added) ✅

### Optimization Opportunities
- Database indexing for user queries

**Status**: ⚠️ Review (moderate regression)

Testing Your Setup

Test 1: Feature Planning

Steps:

Create new issue
Title: "Add dark mode toggle"
Body: "Users should be able to switch between light and dark themes"
Add label: feature

Expected:

Workflow runs (check Actions tab)
Feature folder created: features/0001-dark-mode/
Branch created: feature/0001-dark-mode
Draft PR created
Issue commented with PR link

Verify:

# Check increment folder
ls features/0001-dark-mode/
# Should see: spec.md, plan.md, tasks.md, tests.md, context-manifest.yaml

# Check branch
git fetch
git branch -r | grep dark-mode

Test 2: PR Validation

Steps:

Create branch: test-validation
Make small change to existing file (e.g., README.md)
Commit and push
Open PR

Expected:

Workflow runs
Review comment posted
Status: ✅ or ⚠️ depending on changes

Verify:

Check PR comments for validation report

Test 3: Brownfield Protection

Steps:

Create branch: test-brownfield
Modify existing code in src/ (e.g., add comment)
Commit and push
Open PR

Expected:

Workflow runs
Brownfield check triggered
If docs exist: ✅ Approved
If docs missing: ❌ Blocked with requirements

Verify:

Check PR comments for brownfield report

Test 4: Documentation Update

Steps:

Merge a PR to main
Wait for workflow to complete

Expected:

Workflow runs
Changelog updated
Commit made: "docs: auto-update after merge"

Verify:

git pull origin main
git log -1
# Should see: docs: auto-update after merge

cat .specweave/docs/changelog/2025-10.md
# Should see new entry

Troubleshooting

Issue: Workflow not triggering

Symptoms:

Label issue with 'feature', but nothing happens
PR opened, but no validation comment

Causes & Solutions:

API key not set
- Check: Settings → Secrets → ANTHROPIC_API_KEY exists
- Fix: Add API key
Workflow file missing or disabled
- Check: .github/workflows/specweave-*.yml exists
- Check: Actions tab shows workflow
- Fix: Copy workflow file, commit, push
Incorrect permissions
- Check: Workflow has permissions: set
- Fix: Ensure permissions in YAML
Branch protection blocking bot
- Check: Settings → Branches → Protection rules
- Fix: Add SpecWeave Bot to allowed list

Issue: Authentication failures

Symptoms:

Workflow fails with "401 Unauthorized"
Error: "Invalid API key"

Solutions:

Verify API key

# Test locally
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-4-5-20250929","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

Check key format
- Must start with sk-ant-
- No extra spaces or quotes
- Copy-paste carefully
Regenerate key
- Create new key in Anthropic console
- Update GitHub secret

Issue: High costs

Symptoms:

Anthropic bill higher than expected

Causes & Solutions:

Using wrong model
- Check: .specweave/config.yaml → ai.model
- Fix: Use Sonnet (not Opus)
Too many tokens per run
- Check: Workflow prompts (--max-tokens)
- Fix: Reduce max_tokens in claude_args
Workflow running too often
- Check: Actions tab → Filter by workflow
- Fix: Adjust triggers in YAML
Not using context manifests
- Check: Features have context-manifest.yaml
- Fix: Create manifests to reduce context

Cost optimization tips:

Use context manifests (70%+ reduction)
Set reasonable max_tokens (8000-16000)
Use Haiku for simple tasks
Cache frequently-used context

Issue: Skills not activating

Symptoms:

Workflow runs but doesn't use feature-planner
Skills not detected

Solutions:

Skills not installed

# Install skills
npm run install:skills
# Or manually
cp -r src/skills/* .claude/skills/

SKILL.md missing frontmatter

# Check skill format
head -10 .claude/skills/feature-planner/SKILL.md
# Should see:
# ---
# name: feature-planner
# description: ...
# ---

Description doesn't match
- Check: SKILL.md description includes trigger keywords
- Fix: Update description with relevant keywords

Issue: Brownfield protection too aggressive

Symptoms:

Every PR blocked
Can't merge simple changes

Solutions:

Document existing code first
- Create specs in docs/internal/strategy/
- Create tests in tests/
- Then brownfield protection passes

Disable for specific paths

# .specweave/config.yaml
brownfield:
  enabled: true
  exclude_paths:
    - "docs/**"
    - "tests/**"
    - "*.md"

Temporarily disable (not recommended)
```
brownfield:
  enabled: false
```

Advanced Configuration

Custom Workflow Triggers

Add custom labels:

on:
  issues:
    types: [labeled]

jobs:
  custom-trigger:
    if: |
      github.event.label.name == 'urgent' ||
      github.event.label.name == 'feature'

Conditional Execution

Only run on specific branches:

on:
  pull_request:
    branches:
      - main
      - develop
      - release/**

Only run on specific paths:

on:
  pull_request:
    paths:
      - 'src/**'
      - 'specifications/**'
      - 'features/**'

Multiple AI Models

Use different models for different tasks:

# In workflow
- name: Simple Triage
  uses: anthropics/claude-code-action@v1
  with:
    claude_args: |
      --model haiku  # Fast, cheap
      --max-tokens 4000

- name: Complex Review
  uses: anthropics/claude-code-action@v1
  with:
    claude_args: |
      --model sonnet  # Balanced
      --max-tokens 16000

- name: Deep Analysis
  uses: anthropics/claude-code-action@v1
  with:
    claude_args: |
      --model opus  # Most capable (expensive!)
      --max-tokens 20000

Parallel Execution

Run validations in parallel:

jobs:
  spec-validation:
    runs-on: ubuntu-latest
    # Runs in parallel

  brownfield-check:
    runs-on: ubuntu-latest
    # Runs in parallel

  test-coverage:
    runs-on: ubuntu-latest
    # Runs in parallel

  security-scan:
    runs-on: ubuntu-latest
    # Runs in parallel

Branch-Specific Workflows

Different workflows per branch:

# .github/workflows/specweave-main.yml
on:
  push:
    branches: [main]
jobs:
  # Production validations only

# .github/workflows/specweave-develop.yml
on:
  push:
    branches: [develop]
jobs:
  # Development validations + performance tests

# .github/workflows/specweave-feature.yml
on:
  push:
    branches: [features/**]
jobs:
  # Basic validations only

CLAUDE-CODE-ACTION-INTEGRATION.md - Complete integration analysis
CLAUDE.md - SpecWeave development guide
.specweave/config.yaml - Configuration reference
Troubleshooting Guide - Common issues and solutions

Questions? Open an issue with label question and tag @claude

Need help? Check Troubleshooting or GitHub Actions Logs

Table of Contents​

Overview​

Prerequisites​

Required​

Optional (for advanced features)​

Quick Start​

Step 1: Choose Your Workflow Tier​

Step 2: Add Anthropic API Key to GitHub Secrets​

Step 3: Enable Workflow​

Step 4: Test the Integration​

Workflow Tiers​

Tier 1: Starter (Recommended for New Users)​

Tier 2: Standard (Recommended for Production)​

Tier 3: Enterprise (For Large Organizations)​

Configuration​

.specweave/config.yaml​

Authentication Setup​

Anthropic API (Required)​

JIRA Integration (Optional)​

Slack Integration (Optional)​

Azure DevOps Integration (Optional)​

Workflow Features​

1. Auto Increment Planning​

2. Spec-Aware PR Review​

3. Brownfield Protection​

4. Test Coverage Validation​

5. Auto-Documentation Updates​

6. Security Scanning (Enterprise)​

7. Performance Regression (Enterprise)​

Testing Your Setup​

Test 1: Feature Planning​

Test 2: PR Validation​

Test 3: Brownfield Protection​

Test 4: Documentation Update​

Troubleshooting​

Issue: Workflow not triggering​

Issue: Authentication failures​

Issue: High costs​

Issue: Skills not activating​

Issue: Brownfield protection too aggressive​

Advanced Configuration​

Custom Workflow Triggers​

Conditional Execution​

Multiple AI Models​

Parallel Execution​

Branch-Specific Workflows​

Related Documentation​

Table of Contents

Overview

Prerequisites

Required

Optional (for advanced features)

Quick Start

Step 1: Choose Your Workflow Tier

Step 2: Add Anthropic API Key to GitHub Secrets

Step 3: Enable Workflow

Step 4: Test the Integration

Workflow Tiers

Tier 1: Starter (Recommended for New Users)

Tier 2: Standard (Recommended for Production)

Tier 3: Enterprise (For Large Organizations)

Configuration

.specweave/config.yaml

Authentication Setup

Anthropic API (Required)

JIRA Integration (Optional)

Slack Integration (Optional)

Azure DevOps Integration (Optional)

Workflow Features

1. Auto Increment Planning

2. Spec-Aware PR Review

3. Brownfield Protection

4. Test Coverage Validation

5. Auto-Documentation Updates

6. Security Scanning (Enterprise)

7. Performance Regression (Enterprise)

Testing Your Setup

Test 1: Feature Planning

Test 2: PR Validation

Test 3: Brownfield Protection

Test 4: Documentation Update

Troubleshooting

Issue: Workflow not triggering

Issue: Authentication failures

Issue: High costs

Issue: Skills not activating

Issue: Brownfield protection too aggressive

Advanced Configuration

Custom Workflow Triggers

Conditional Execution

Multiple AI Models

Parallel Execution

Branch-Specific Workflows

Related Documentation