You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+
## Repository Purpose
6
+
7
+
This repository provides centralized, reusable GitHub Actions workflows for Claude AI integration across dotCMS and related projects. It implements a DRY approach by consolidating Claude workflow logic into orchestrator and executor patterns that can be consumed by other repositories.
8
+
9
+
## Architecture Overview
10
+
11
+
The repository implements a two-workflow architecture:
12
+
13
+
### Core Workflows
14
+
-**Claude Orchestrator** (`.github/workflows/claude-orchestrator.yml`): Routes different trigger types (PR events, comments, issues) to appropriate execution modes. Handles both interactive (@claude mentions) and automatic review modes.
15
+
-**Claude Executor** (`.github/workflows/claude-executor.yml`): The execution engine that runs Claude AI actions with configurable tools, timeouts, and runners.
16
+
17
+
### Key Design Patterns
18
+
-**Reusable Workflows**: Both workflows use `workflow_call` to be consumed by other repositories
19
+
-**Conditional Execution**: Orchestrator prevents duplicate runs by routing triggers to specific jobs
20
+
-**Parameterization**: Workflows accept inputs for customization (prompts, tools, timeouts, runners)
21
+
-**Security Isolation**: Each consuming repository must provide its own `ANTHROPIC_API_KEY` for cost tracking and security
> **Note:** For main usage instructions and up-to-date examples, see [README.md](./README.md).
4
+
5
+
## Overview
6
+
This document outlines the migration of Claude AI workflows to the centralized `dotCMS/claude-workflows` repository to implement DRY principles and enable reuse across multiple repositories.
7
+
8
+
## Files Created for claude-workflows Repository
9
+
10
+
The following files should exist in the `dotCMS/claude-workflows` repository:
11
+
12
+
### 1. `.github/workflows/claude-executor.yml`
13
+
Location: `claude-executor-reusable.yml` (rename to `claude-executor.yml`)
14
+
- Reusable workflow that handles Claude AI execution
Location: `claude-orchestrator-reusable.yml` (rename to `claude-orchestrator.yml`)
20
+
- Reusable workflow that orchestrates Claude interactions
21
+
- Handles all trigger events (comments, PRs, issues)
22
+
- Configurable prompts, tools, and executor workflow reference
23
+
24
+
## Migration Benefits
25
+
26
+
### Before (Current State)
27
+
- Each repository maintains its own Claude workflow files
28
+
- Duplication of logic across repositories
29
+
- Updates require changes in multiple places
30
+
- Inconsistent configurations between repositories
31
+
32
+
### After (Centralized State)
33
+
- Single source of truth for Claude workflows
34
+
- Repository-specific configurations via parameters
35
+
- Easier maintenance and updates
36
+
- Consistent behavior across all repositories
37
+
- DRY principle implementation
38
+
39
+
## Implementation Steps
40
+
41
+
### Step 1: Ensure Files Exist in claude-workflows Repository
42
+
43
+
> **Historical Note:** This step is already completed in this repository. The required workflows are present and correctly named. For forks or future migrations, ensure the following files exist in the correct locations:
44
+
> -`.github/workflows/claude-executor.yml`
45
+
> -`.github/workflows/claude-orchestrator.yml`
46
+
47
+
### Step 2: Repository Configuration
48
+
The infrastructure-as-code repository has been updated to:
49
+
- Reference centralized workflows from `dotCMS/claude-workflows`
1.**Ensure reusable workflows exist** in claude-workflows repository (already done here)
84
+
2.**Test the migration** with a sample PR
85
+
3.**Apply to other repositories** using the same pattern
86
+
4.**Document usage** for other teams
87
+
88
+
## Benefits for Other Repositories
89
+
90
+
Other dotCMS repositories can now easily add Claude support by:
91
+
1. Creating a simple orchestrator workflow that calls the centralized version
92
+
2. Customizing allowed tools for their specific needs
93
+
3. Setting repository-specific prompts and configurations
94
+
4. Maintaining consistent Claude behavior across the organization
95
+
96
+
This migration addresses issue [dotCMS/dotcat#213](https://github.com/dotCMS/dotcat/issues/213) and establishes the foundation for organization-wide Claude workflow standardization.
3. **Configure your `ANTHROPIC_API_KEY` secret** as described below.
36
+
4. **(Optional) Customize prompts, allowed tools, and runner as needed.**
37
+
38
+
---
39
+
40
+
## 📚 Migration Details
41
+
42
+
For a comprehensive migration guide—including step-by-step instructions, validation tips, and infrastructure-specific configuration examples—see [CLAUDE_WORKFLOW_MIGRATION.md](./CLAUDE_WORKFLOW_MIGRATION.md).
43
+
44
+
---
45
+
46
+
## Top-Level Points
47
+
48
+
- **Centralized, DRY, and maintainable:** All Claude logic is now in one place, making updates and improvements easy.
49
+
- **Repo-level flexibility:** Each repository can override prompts, tools, and other settings via workflow inputs.
50
+
- **Security & cost management:** Each repo must provide its own Anthropic API key for isolation and accountability.
51
+
- **No more standalone code review workflow:** All code review and other Claude actions are routed through the orchestrator/executor pattern.
52
+
53
+
---
54
+
4
55
## Important: Security and Cost Management
5
56
6
57
**⚠️ 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.
7
58
8
59
**Why we require per-repository API keys:**
9
60
10
61
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.
11
-
12
62
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.
13
-
14
63
3. **Usage Control**: Individual repositories can set their own API limits and monitoring, preventing runaway costs from affecting other projects.
15
-
16
64
4. **Compliance**: Many organizations require API key isolation for audit trails and security compliance.
17
65
18
66
**What this means for you:**
@@ -21,17 +69,17 @@ Reusable Claude AI GitHub Actions workflows and config for dotCMS and related pr
21
69
- The workflow will **fail** if the API key is not provided
22
70
- Each repository is responsible for its own API costs and usage
23
71
72
+
---
73
+
24
74
## Available Workflows
25
75
26
-
### Claude Code Review (`claude-code-review.yml`)
27
-
Provides AI-powered code review using Claude AI for pull requests and commits.
76
+
### Claude Orchestrator (`claude-orchestrator.yml`)
77
+
Routes all Claude triggers (PRs, issues, comments, reviews) to the correct execution mode and calls the executor workflow.
78
+
79
+
### Claude Executor (`claude-executor.yml`)
80
+
Handles the actual execution of Claude actions, with configurable parameters (prompts, allowed tools, runner, etc.).
| `files_to_review` | Comma-separated list of specific files to review | No | All changed files |
84
-
| `review_focus` | Review focus area | No | `general` |
85
-
| `max_files` | Maximum number of files to review | No | `10` |
86
-
87
-
**Review Focus Options:**
88
-
- `general`: Overall code quality, bugs, and improvements
89
-
- `security`: Security vulnerabilities and best practices
90
-
- `performance`: Performance issues and optimizations
91
-
- `best-practices`: Code quality and maintainability
92
-
93
-
### 4. Required Secrets
94
-
95
-
| Secret | Description | Required | Notes |
96
-
|--------|-------------|----------|-------|
97
-
| `ANTHROPIC_API_KEY` | Your repository's Anthropic API key | **Yes** | Must be configured in each consuming repository. The workflow will fail without this secret. |
124
+
| `automatic_review_prompt` | Custom prompt for automatic PR reviews | No | See orchestrator default |
125
+
| `allowed_tools` | Custom allowed tools configuration | No | See orchestrator default |
126
+
| `timeout_minutes` | Timeout for Claude execution | No | 15 |
127
+
| `runner` | GitHub runner to use | No | ubuntu-latest |
98
128
99
-
**⚠️ Critical**: The `ANTHROPIC_API_KEY` secret is mandatory and must be passed to the reusable workflow. This is not optional - it's a security and cost management requirement. See the "Security and Cost Management" section above for details.
0 commit comments