ai-workflows

Reusable Claude AI GitHub Actions workflows and config for dotCMS and related projects

🚀 Centralized Claude Workflows: Migration & Overview

This repository now provides a centralized, reusable system for all Claude AI GitHub Actions workflows.

• Replaces the pilot workflow previously used in dotcms/infrastructure-as-code.
• Keeps things DRY and maintainable by consolidating logic into orchestrator and executor workflows.
• Still allows full repo-level customization via workflow inputs (prompts, allowed tools, runners, etc.).

---

Migration Guide: From Pilot to Centralized Workflows

If you previously used the pilot Claude workflow in dotcms/infrastructure-as-code, follow these steps:

📋 Migration Checklist

1. Remove references to the old pilot workflow in your repository's workflow files.

2. Update your workflow to use the new orchestrator with version tags:

   jobs:
     claude:
       uses: dotCMS/ai-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
       with:
         trigger_mode: automatic  # or 'interactive' for @claude mentions
         # Customize as needed for your repo
         allowed_tools: |
           Bash(terraform plan)
           Bash(git status)
         direct_prompt: |
           Please review this pull request for code quality, security, and best practices.
         enable_mention_detection: true  # Enable @claude mention detection
       secrets:
         ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

   ⚠️ Important: Always use version tags (e.g., @v1.0.0) instead of @main for production stability. Using @main can cause unexpected behavior when the main branch is updated.

3. Configure your ANTHROPIC_API_KEY secret as described below.

4. (Optional) Customize prompts, allowed tools, and runner as needed.

5. Test your migration with a sample PR or @claude mention.

---

📚 Migration Details

For a comprehensive migration guide—including step-by-step instructions, validation tips, and infrastructure-specific configuration examples—see CLAUDE_WORKFLOW_MIGRATION.md.

---

Top-Level Points

• Centralized, DRY, and maintainable: All Claude logic is now in one place, making updates and improvements easy.
• Repo-level flexibility: Each repository can override prompts, tools, and other settings via workflow inputs.
• Security & cost management: Each repo must provide its own Anthropic API key for isolation and accountability.
• No more standalone code review workflow: All code review and other Claude actions are routed through the orchestrator/executor pattern.

---

🗺️ Workflow Visualization

flowchart TD
    A["GitHub Event (PR, Issue, Comment, Review)"] --> B["Orchestrator Workflow (claude-orchestrator.yml)"]
    B -->|"Determines trigger type and mode"| C["Executor Workflow (claude-executor.yml)"]
    C --> D["Claude AI Action (Review, Comment, etc.)"]

    subgraph "Repo Level"
      A
    end
    subgraph "Centralized Workflows"
      B
      C
    end
    
    B -.->|"Custom inputs: prompts, tools, runner"| C
    C -.->|"Repo-specific config from orchestrator"| D

Loading

---

Important: Security and Cost Management

⚠️ API Key Requirement: All workflows in this repository require each consuming repository to provide its own Anthropic API key. This is a mandatory security and cost management requirement.

Why we require per-repository API keys:

1. Cost Tracking & Accountability: Each repository's Claude AI usage is tracked separately in the Anthropic console, allowing for detailed cost attribution and budget management per project.
2. Security Isolation: If a repository experiences unauthorized or excessive usage, it only affects that repository's API key and budget, not a shared organizational key.
3. Usage Control: Individual repositories can set their own API limits and monitoring, preventing runaway costs from affecting other projects.
4. Compliance: Many organizations require API key isolation for audit trails and security compliance.

What this means for you:

• You must configure an ANTHROPIC_API_KEY secret in your repository
• You must pass this secret to the reusable workflow in the secrets: section
• The workflow will fail if the API key is not provided
• Each repository is responsible for its own API costs and usage

---

Available Workflows

Claude Orchestrator (claude-orchestrator.yml)

Routes all Claude triggers (PRs, issues, comments, reviews) to the correct execution mode. Features built-in @claude mention detection and support for custom trigger conditions.

Claude Executor (claude-executor.yml)

Handles the actual execution of Claude actions, with configurable parameters (prompts, allowed tools, runner, etc.).

---

Setup Instructions

1. Repository Secret Configuration

Each consuming repository must configure its own Anthropic API key:

1. Go to your repository's Settings → Secrets and variables → Actions
2. Create a new repository secret named ANTHROPIC_API_KEY
3. Set the value to your Anthropic API key

2. Using the Centralized Claude Workflow

Create a workflow file in your repository at .github/workflows/claude-review.yml (or similar):

name: Claude AI Integration

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]  
  issues:
    types: [opened, assigned]
  pull_request_review:
    types: [submitted]
  pull_request:
    types: [opened, synchronize]

jobs:
  # Interactive Claude mentions using built-in detection
  claude-interactive:
    uses: dotCMS/ai-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
    with:
      trigger_mode: interactive
      allowed_tools: |
        Bash(git status)
        Bash(git diff)
      enable_mention_detection: true  # Uses built-in @claude detection
    secrets:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

  # Automatic PR reviews (no @claude mention required)
  claude-automatic:
    if: github.event_name == 'pull_request'
    uses: dotCMS/ai-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
    with:
      trigger_mode: automatic
      direct_prompt: |
        Please review this pull request for code quality, security, and best practices.
      allowed_tools: |
        Bash(git status)
        Bash(git diff)
      enable_mention_detection: false  # No mention detection for automatic reviews
    secrets:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

3. Workflow Inputs

Input	Description	Required	Default
trigger_mode	Mode: interactive or automatic	Yes	-
direct_prompt	Custom prompt for automatic mode	No	-
allowed_tools	Custom allowed tools configuration	No	Bash(git status) Bash(git diff)
timeout_minutes	Timeout for Claude execution	No	15
runner	GitHub runner to use	No	ubuntu-latest
enable_mention_detection	Enable built-in @claude mention detection	No	true
custom_trigger_condition	Custom condition to override default detection	No	-

4. Advanced: Custom Trigger Conditions

For advanced use cases beyond @claude mentions, use custom_trigger_condition:

jobs:
  claude-security-review:
    uses: dotCMS/ai-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
    with:
      trigger_mode: automatic
      custom_trigger_condition: |
        github.event_name == 'pull_request' && (
          contains(github.event.pull_request.title, 'security') ||
          contains(github.event.pull_request.body, 'vulnerability')
        )
      direct_prompt: |
        This appears to be a security-related change. Please review for security implications.
      enable_mention_detection: false  # Disable default detection when using custom condition
    secrets:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Note: When using custom_trigger_condition, set enable_mention_detection: false to avoid conflicts.

---

Examples

See the examples/ directory for complete workflow examples:

• consumer-repo-workflow.yml - Basic usage with @claude mentions
• infrastructure-consumer-workflow.yml - Infrastructure-specific tooling
• advanced-custom-triggers.yml - Advanced examples using custom_trigger_condition for specialized triggers (urgent issues, security reviews, config changes, etc.)

Quick Examples

Basic @claude mention detection:

uses: dotCMS/ai-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
with:
  trigger_mode: interactive
  enable_mention_detection: true

Automatic PR reviews:

uses: dotCMS/ai-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
with:
  trigger_mode: automatic
  direct_prompt: "Review this PR for quality and security."
  enable_mention_detection: false

Custom triggers for urgent issues:

uses: dotCMS/ai-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
with:
  trigger_mode: interactive
  custom_trigger_condition: |
    github.event_name == 'issues' && 
    contains(github.event.issue.labels.*.name, 'urgent')
  enable_mention_detection: false