diff --git a/README.md b/README.md index 3597680fd..b640830b8 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ A general-purpose [Claude Code](https://claude.ai/code) action for GitHub PRs an - 🛠️ **Flexible Tool Access**: Access to GitHub APIs and file operations (additional tools can be enabled via configuration) - 📋 **Progress Tracking**: Visual progress indicators with checkboxes that dynamically update as Claude completes tasks - 🏃 **Runs on Your Infrastructure**: The action executes entirely on your own GitHub runner (Anthropic API calls go to your chosen provider) +- 🎯 **Custom Prompts**: Create tailored prompts with variable substitution (`$PR_NUMBER`, `$CHANGED_FILES`, etc.) for automated workflows ## Quickstart @@ -29,7 +30,7 @@ This command will guide you through setting up the GitHub app and required secre - [Setup Guide](./docs/setup.md) - Manual setup, custom GitHub apps, and security best practices - [Usage Guide](./docs/usage.md) - Basic usage, workflow configuration, and input parameters -- [Custom Automations](./docs/custom-automations.md) - Examples of automated workflows and custom prompts +- [Custom Automations](./docs/custom-automations.md) - Automated workflows, custom prompts with variable substitution - [Configuration](./docs/configuration.md) - MCP servers, permissions, environment variables, and advanced settings - [Experimental Features](./docs/experimental.md) - Execution modes and network restrictions - [Cloud Providers](./docs/cloud-providers.md) - AWS Bedrock and Google Vertex AI setup diff --git a/docs/custom-automations.md b/docs/custom-automations.md index d3693d413..cf602af62 100644 --- a/docs/custom-automations.md +++ b/docs/custom-automations.md @@ -62,7 +62,7 @@ Perfect for automatically reviewing PRs from new team members, external contribu ## Custom Prompt Templates -Use `override_prompt` for complete control over Claude's behavior with variable substitution: +Use `override_prompt` for complete control over Claude's behavior with variable substitution. Variables are replaced with formatted data from the GitHub context. ```yaml - uses: anthropics/claude-code-action@beta @@ -82,10 +82,81 @@ Use `override_prompt` for complete control over Claude's behavior with variable Provide severity ratings (Critical/High/Medium/Low) for any issues found. ``` -The `override_prompt` feature supports these variables: +### Available Variables + +| Variable | Description | Example Output | Availability | +|----------|-------------|----------------|--------------| +| `$REPOSITORY` | Full repository name | `owner/repo` | All contexts | +| `$PR_NUMBER` | Pull request number | `123` | PR contexts only | +| `$ISSUE_NUMBER` | Issue number | `456` | Issue contexts only | +| `$PR_TITLE` | Pull request title | `feat: add new feature` | PR contexts only | +| `$ISSUE_TITLE` | Issue title | `Bug: Login not working` | Issue contexts only | +| `$PR_BODY` | Formatted PR description with images replaced | Multi-line markdown content | PR contexts only | +| `$ISSUE_BODY` | Formatted issue description with images replaced | Multi-line markdown content | Issue contexts only | +| `$PR_COMMENTS` | Formatted PR comments | `[username at 2024-01-01]: Comment text`

`[user2 at 2024-01-02]: Another comment` | PR contexts only | +| `$ISSUE_COMMENTS` | Formatted issue comments | Same format as PR_COMMENTS | Issue contexts only | +| `$REVIEW_COMMENTS` | Formatted PR review comments with inline code locations | `[Review by user at 2024-01-01]: APPROVED`
`Review body text`
` [Comment on src/file.js:10]: Inline comment` | PR contexts only | +| `$CHANGED_FILES` | List of changed files with stats and SHAs | `- src/file.js (MODIFIED) +10/-5 SHA: abc123`
`- docs/readme.md (ADDED) +50/-0 SHA: def456` | PR contexts only | +| `$TRIGGER_COMMENT` | The comment that triggered Claude | `@claude please review this` | Comment events only | +| `$TRIGGER_USERNAME` | Username who triggered the action | `johndoe` | All contexts | +| `$BRANCH_NAME` | Current branch name (claudeBranch or baseBranch) | `feature-123` or `main` | All contexts | +| `$BASE_BRANCH` | Base branch for PRs/issues | `main` | All contexts | +| `$EVENT_TYPE` | GitHub event type | `pull_request_review_comment`, `issues`, etc. | All contexts | +| `$IS_PR` | Whether context is a PR | `true` or `false` | All contexts | + +### Important Notes + +- **Empty variables**: Variables that don't apply to the current context (e.g., `$PR_NUMBER` in an issue) will be replaced with empty strings +- **Image handling**: `$PR_BODY`, `$ISSUE_BODY`, and comment variables automatically have image URLs replaced with local file paths +- **Formatting**: Comments include author and timestamp, changed files include modification stats +- **Mode availability**: Variable substitution works in all modes (tag, review, agent) when using `override_prompt` + +### Variable Output Examples + +#### Comments Format + +```text +$PR_COMMENTS outputs: +[alice at 2024-12-01T10:30:00Z]: This looks great! Just one suggestion below. + +[bob at 2024-12-01T11:00:00Z]: I agree with Alice. Also, can we add tests? +``` + +#### Changed Files Format + +```text +$CHANGED_FILES outputs: +- src/components/Button.tsx (MODIFIED) +25/-10 SHA: a1b2c3d4 +- src/components/Button.test.tsx (ADDED) +100/-0 SHA: e5f6g7h8 +- src/old/Legacy.js (DELETED) +0/-150 SHA: deleted +``` + +#### Review Comments Format + +```text +$REVIEW_COMMENTS outputs: +[Review by charlie at 2024-12-01T12:00:00Z]: REQUEST_CHANGES +Please address the security concern below. + [Comment on src/auth.js:45]: This could be vulnerable to SQL injection + [Comment on src/auth.js:67]: Consider using prepared statements here +``` + +### Mode-Specific Considerations + +#### Review Mode + +- All PR-related variables are available since review mode only works on pull requests +- `$TRIGGER_COMMENT` contains the review comment if triggered by a review +- Variable substitution fully supported with `override_prompt` + +#### Agent Mode + +- Typically used for automation without PR/issue context +- PR/issue-specific variables will be empty when no context is available +- Variable substitution fully supported with `override_prompt` + +#### Tag Mode -- `$REPOSITORY`, `$PR_NUMBER`, `$ISSUE_NUMBER` -- `$PR_TITLE`, `$ISSUE_TITLE`, `$PR_BODY`, `$ISSUE_BODY` -- `$PR_COMMENTS`, `$ISSUE_COMMENTS`, `$REVIEW_COMMENTS` -- `$CHANGED_FILES`, `$TRIGGER_COMMENT`, `$TRIGGER_USERNAME` -- `$BRANCH_NAME`, `$BASE_BRANCH`, `$EVENT_TYPE`, `$IS_PR` +- Full variable support for both PR and issue contexts +- Variables adapt based on whether triggered on a PR or issue +- Variable substitution fully supported with `override_prompt` diff --git a/docs/usage.md b/docs/usage.md index 0d8ed421e..852d30b74 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -52,7 +52,7 @@ jobs: | `anthropic_api_key` | Anthropic API key (required for direct API, not needed for Bedrock/Vertex) | No\* | - | | `claude_code_oauth_token` | Claude Code OAuth token (alternative to anthropic_api_key) | No\* | - | | `direct_prompt` | Direct prompt for Claude to execute automatically without needing a trigger (for automated workflows) | No | - | -| `override_prompt` | Complete replacement of Claude's prompt with custom template (supports variable substitution) | No | - | +| `override_prompt` | Complete replacement of Claude's prompt with custom template. Supports `$VARIABLE` substitution for GitHub context data. See [Custom Automations](./custom-automations.md#custom-prompt-templates) for available variables and examples. | No | - | | `base_branch` | The base branch to use for creating new branches (e.g., 'main', 'develop') | No | - | | `max_turns` | Maximum number of conversation turns Claude can take (limits back-and-forth exchanges) | No | - | | `timeout_minutes` | Timeout in minutes for execution | No | `30` |