diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 96824d1..74e6140 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,20 +50,6 @@ Thank you for your interest in contributing to Claude Code Action! This document bun test ``` -2. **Integration Tests** (using GitHub Actions locally): - - ```bash - ./test-local.sh - ``` - - This script: - - - Installs `act` if not present (requires Homebrew on macOS) - - Runs the GitHub Action workflow locally using Docker - - Requires your `ANTHROPIC_API_KEY` to be set - - On Apple Silicon Macs, the script automatically adds the `--container-architecture linux/amd64` flag to avoid compatibility issues. - ## Pull Request Process 1. Create a new branch from `main`: @@ -103,13 +89,7 @@ Thank you for your interest in contributing to Claude Code Action! This document When modifying the action: -1. Test locally with the test script: - - ```bash - ./test-local.sh - ``` - -2. Test in a real GitHub Actions workflow by: +1. Test in a real GitHub Actions workflow by: - Creating a test repository - Using your branch as the action source: ```yaml diff --git a/example-dispatch-workflow.yml b/example-dispatch-workflow.yml new file mode 100644 index 0000000..74cd95d --- /dev/null +++ b/example-dispatch-workflow.yml @@ -0,0 +1,73 @@ +name: Claude Task Executor + +on: + repository_dispatch: + types: [claude-task] + +permissions: + contents: write + pull-requests: write + issues: write + id-token: write # Required for OIDC authentication + +jobs: + execute-claude-task: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Execute Claude Task + uses: anthropics/claude-code-action@main + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + # Base branch for creating task branches + base_branch: main + # Optional: Custom instructions for Claude + custom_instructions: | + Follow the CLAUDE.md guidelines strictly. + Commit changes with descriptive messages. + # Optional: Tool restrictions + allowed_tools: | + file_editor + bash_command + github_comment + mcp__github__create_or_update_file + # Optional: Anthropic API configuration + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + # Or use AWS Bedrock + # aws_access_key: ${{ secrets.AWS_ACCESS_KEY_ID }} + # aws_secret_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + # aws_region: us-east-1 + # Or use Google Vertex AI + # google_credentials: ${{ secrets.GOOGLE_CREDENTIALS }} + # vertex_project: my-project + # vertex_location: us-central1 +# Example: Triggering this workflow from another service +# +# curl -X POST \ +# https://api.github.com/repos/owner/repo/dispatches \ +# -H "Authorization: token $GITHUB_TOKEN" \ +# -H "Accept: application/vnd.github.v3+json" \ +# -d '{ +# "event_type": "claude-task", +# "client_payload": { +# "description": "Analyze the codebase and create a comprehensive test suite for the authentication module", +# "progress_endpoint": "https://api.example.com/claude/progress", +# "correlation_id": "task-auth-tests-2024-01-17" +# } +# }' +# +# The progress_endpoint will receive POST requests with: +# { +# "repository": "owner/repo", +# "run_id": "123456789", +# "correlation_id": "task-auth-tests-2024-01-17", +# "status": "in_progress" | "completed" | "failed", +# "message": "Current progress description", +# "completed_tasks": ["task1", "task2"], +# "current_task": "Working on task3", +# "timestamp": "2024-01-17T12:00:00Z" +# } +# +# Authentication: Progress updates include a GitHub OIDC token in the Authorization header diff --git a/pr-summary.md b/pr-summary.md new file mode 100644 index 0000000..0830649 --- /dev/null +++ b/pr-summary.md @@ -0,0 +1,118 @@ +## Summary + +Adds support for `repository_dispatch` events, enabling backend services to programmatically trigger Claude to perform tasks and receive progress updates via API. + +## Architecture + +```mermaid +sequenceDiagram + participant Backend as Backend Service + participant GH as GitHub + participant Action as Claude Action + participant Claude as Claude + participant MCP as Progress MCP Server + participant API as Progress API + + Backend->>GH: POST /repos/{owner}/{repo}/dispatches + Note over Backend,GH: Payload includes:
- description (task)
- progress_endpoint
- correlation_id + + GH->>Action: Trigger workflow
(repository_dispatch) + + Action->>Action: Parse dispatch payload + Note over Action: Extract task description,
endpoint, correlation_id + + Action->>MCP: Install Progress Server + Note over MCP: Configure with:
- PROGRESS_ENDPOINT
- CORRELATION_ID
- GITHUB_RUN_ID + + Action->>Claude: Execute task with
MCP tools available + + loop Task Execution + Claude->>MCP: update_claude_progress() + MCP->>MCP: Get OIDC token + MCP->>API: POST progress update + Note over API: Payload includes:
- correlation_id
- status
- message
- completed_tasks + API->>Backend: Forward update + end + + Claude->>Action: Task complete + Action->>GH: Commit changes +``` + +## Key Features + +### 1. Repository Dispatch Support + +- New event handler for `repository_dispatch` events +- Extracts task description, progress endpoint, and correlation ID from `client_payload` +- Bypasses GitHub UI interaction for fully programmatic operation + +### 2. Progress Reporting MCP Server + +- New MCP server (`progress-server.ts`) for sending progress updates +- OIDC authentication for secure API communication +- Includes correlation ID in all updates for request tracking + +### 3. Simplified Dispatch Prompts + +- Focused instructions for dispatch events (no PR/issue context) +- Clear directives: answer questions or implement changes +- Automatic progress updates at start and completion + +## Implementation Details + +### Triggering a Dispatch + +```bash +curl -X POST \ + https://api.github.com/repos/{owner}/{repo}/dispatches \ + -H "Authorization: token $GITHUB_TOKEN" \ + -H "Accept: application/vnd.github.v3+json" \ + -d '{ + "event_type": "claude-task", + "client_payload": { + "description": "Implement a new feature that...", + "progress_endpoint": "https://api.example.com/progress", + "correlation_id": "req-123-abc" + } + }' +``` + +### Progress Update Payload + +```json +{ + "repository": "owner/repo", + "run_id": "123456789", + "correlation_id": "req-123-abc", + "status": "in_progress", + "message": "Implementing feature...", + "completed_tasks": ["Setup environment", "Created base structure"], + "current_task": "Writing tests", + "timestamp": "2024-01-17T12:00:00Z" +} +``` + +## Security + +- **OIDC Authentication**: All progress updates use GitHub OIDC tokens +- **Correlation IDs**: Included in request body (not URL) for security +- **Endpoint Validation**: Progress endpoint must be explicitly provided +- **No Credential Storage**: Tokens are generated per-request + +## Testing + +To test the repository_dispatch flow: + +1. Configure workflow with `repository_dispatch` trigger +2. Send dispatch event with required payload +3. Monitor GitHub Actions logs for execution +4. Verify progress updates at configured endpoint + +## Changes + +- Added `repository_dispatch` event handling in `context.ts` +- Created new `progress-server.ts` MCP server +- Updated `isDispatch` flag across all event types +- Modified prompt generation for dispatch events +- Made `githubData` optional for dispatch workflows +- Added correlation ID support throughout the pipeline