diff --git a/.claude/commands/label-issue.md b/.claude/commands/label-issue.md index 62497ef65..f8ae5e626 100644 --- a/.claude/commands/label-issue.md +++ b/.claude/commands/label-issue.md @@ -17,7 +17,6 @@ TASK OVERVIEW: 1. First, fetch the list of labels available in this repository by running: `./scripts/gh.sh label list`. Run exactly this command with nothing else. 2. Next, use gh wrapper commands to get context about the issue: - - Use `./scripts/gh.sh issue view ${{ github.event.issue.number }}` to retrieve the current issue's details - Use `./scripts/gh.sh search issues` to find similar issues that might provide context for proper categorization - `./scripts/gh.sh` is a wrapper for `gh` CLI. Example commands: @@ -28,7 +27,6 @@ TASK OVERVIEW: - `./scripts/edit-issue-labels.sh` — apply labels to the issue 3. Analyze the issue content, considering: - - The issue title and description - The type of issue (bug report, feature request, question, etc.) - Technical areas mentioned @@ -37,7 +35,6 @@ TASK OVERVIEW: - Components affected 4. Select appropriate labels from the available labels list provided above: - - Choose labels that accurately reflect the issue's nature - Be specific but comprehensive - IMPORTANT: Add a priority label (P1, P2, or P3) based on the label descriptions from ./scripts/gh.sh label list diff --git a/base-action/CONTRIBUTING.md b/base-action/CONTRIBUTING.md index 4dc259263..4ab35815e 100644 --- a/base-action/CONTRIBUTING.md +++ b/base-action/CONTRIBUTING.md @@ -57,7 +57,6 @@ Thank you for your interest in contributing to Claude Code Base Action! This doc ``` 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 diff --git a/base-action/README.md b/base-action/README.md index 495ebf6fb..6fdbe06f6 100644 --- a/base-action/README.md +++ b/base-action/README.md @@ -85,26 +85,26 @@ Add the following to your workflow file: ## Inputs -| Input | Description | Required | Default | -| ------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------- | -| `prompt` | The prompt to send to Claude Code | No\* | '' | -| `prompt_file` | Path to a file containing the prompt to send to Claude Code | No\* | '' | -| `allowed_tools` | Comma-separated list of allowed tools for Claude Code to use | No | '' | -| `disallowed_tools` | Comma-separated list of disallowed tools that Claude Code cannot use | No | '' | -| `max_turns` | Maximum number of conversation turns (default: no limit) | No | '' | -| `mcp_config` | Path to the MCP configuration JSON file, or MCP configuration JSON string | No | '' | -| `settings` | Path to Claude Code settings JSON file, or settings JSON string | No | '' | -| `system_prompt` | Override system prompt | No | '' | -| `append_system_prompt` | Append to system prompt | No | '' | -| `claude_env` | Custom environment variables to pass to Claude Code execution (YAML multiline format) | No | '' | -| `model` | Model to use (provider-specific format required for Bedrock/Vertex) | No | 'claude-4-0-sonnet-20250219' | -| `anthropic_model` | DEPRECATED: Use 'model' instead | No | 'claude-4-0-sonnet-20250219' | -| `fallback_model` | Enable automatic fallback to specified model when default model is overloaded | No | '' | -| `anthropic_api_key` | Anthropic API key (required for direct Anthropic API) | No | '' | -| `claude_code_oauth_token` | Claude Code OAuth token (alternative to anthropic_api_key) | No | '' | -| `use_bedrock` | Use Amazon Bedrock with OIDC authentication instead of direct Anthropic API | No | 'false' | -| `use_vertex` | Use Google Vertex AI with OIDC authentication instead of direct Anthropic API | No | 'false' | -| `use_node_cache` | Whether to use Node.js dependency caching (set to true only for Node.js projects with lock files) | No | 'false' | +| Input | Description | Required | Default | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------- | +| `prompt` | The prompt to send to Claude Code | No\* | '' | +| `prompt_file` | Path to a file containing the prompt to send to Claude Code | No\* | '' | +| `allowed_tools` | Comma-separated list of allowed tools for Claude Code to use | No | '' | +| `disallowed_tools` | Comma-separated list of disallowed tools that Claude Code cannot use | No | '' | +| `max_turns` | Maximum number of conversation turns (default: no limit) | No | '' | +| `mcp_config` | Path to the MCP configuration JSON file, or MCP configuration JSON string | No | '' | +| `settings` | Path to Claude Code settings JSON file, or settings JSON string | No | '' | +| `system_prompt` | Override system prompt | No | '' | +| `append_system_prompt` | Append to system prompt | No | '' | +| `claude_env` | Custom environment variables to pass to Claude Code execution (YAML multiline format) | No | '' | +| `model` | Model to use (provider-specific format required for Bedrock/Vertex) | No | 'claude-4-0-sonnet-20250219' | +| `anthropic_model` | DEPRECATED: Use 'model' instead | No | 'claude-4-0-sonnet-20250219' | +| `fallback_model` | Enable automatic fallback to specified model when default model is overloaded | No | '' | +| `anthropic_api_key` | Anthropic API key (required for direct Anthropic API) | No | '' | +| `claude_code_oauth_token` | Claude Code OAuth token (alternative to anthropic_api_key) | No | '' | +| `use_bedrock` | Use Amazon Bedrock with OIDC authentication instead of direct Anthropic API | No | 'false' | +| `use_vertex` | Use Google Vertex AI with OIDC authentication instead of direct Anthropic API | No | 'false' | +| `use_node_cache` | Whether to use Node.js dependency caching (set to true only for Node.js projects with lock files) | No | 'false' | | `show_full_output` | Show full JSON output (⚠️ May expose secrets - see [security docs](../docs/security.md#️-full-output-security-warning)) | No | 'false'\*\* | \*Either `prompt` or `prompt_file` must be provided, but not both. @@ -490,7 +490,6 @@ This example shows how to use OIDC authentication with GCP Vertex AI: To securely use your Anthropic API key: 1. Add your API key as a repository secret: - - Go to your repository's Settings - Navigate to "Secrets and variables" → "Actions" - Click "New repository secret" diff --git a/docs/configuration.md b/docs/configuration.md index eb352b349..23c42af37 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -116,7 +116,6 @@ The `additional_permissions` input allows Claude to access GitHub Actions workfl To allow Claude to view workflow run results, job logs, and CI status: 1. **Grant the necessary permission to your GitHub token**: - - When using the default `GITHUB_TOKEN`, add the `actions: read` permission to your workflow: ```yaml diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 0d57a9c16..464e36359 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -228,12 +228,10 @@ jobs: The action now automatically detects the appropriate mode: 1. **If `prompt` is provided** → Runs in **automation mode** - - Executes immediately without waiting for @claude mentions - Perfect for scheduled tasks, PR automation, etc. 2. **If no `prompt` but @claude is mentioned** → Runs in **interactive mode** - - Waits for and responds to @claude mentions - Creates tracking comments with progress diff --git a/docs/security.md b/docs/security.md index d36f06122..34c47b0c6 100644 --- a/docs/security.md +++ b/docs/security.md @@ -85,14 +85,12 @@ Commits will show as verified and attributed to the GitHub account that owns the ``` 2. Add the **public key** to your GitHub account: - - Go to GitHub → Settings → SSH and GPG keys - Click "New SSH key" - Select **Key type: Signing Key** (important) - Paste the contents of `~/.ssh/signing_key.pub` 3. Add the **private key** to your repository secrets: - - Go to your repo → Settings → Secrets and variables → Actions - Create a new secret named `SSH_SIGNING_KEY` - Paste the contents of `~/.ssh/signing_key` diff --git a/docs/setup.md b/docs/setup.md index e0c7f56c8..5c61c9f5e 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -31,27 +31,23 @@ The fastest way to create a custom GitHub App is using our pre-configured manife **🚀 [Download the Quick Setup Tool](./create-app.html)** (Right-click → "Save Link As" or "Download Linked File") After downloading, open `create-app.html` in your web browser: - - **For Personal Accounts:** Click the "Create App for Personal Account" button - **For Organizations:** Enter your organization name and click "Create App for Organization" The tool will automatically configure all required permissions and submit the manifest. Alternatively, you can use the manifest file directly: - - Use the [`github-app-manifest.json`](../github-app-manifest.json) file from this repository - Visit https://github.com/settings/apps/new (for personal) or your organization's app settings - Look for the "Create from manifest" option and paste the JSON content 2. **Complete the creation flow:** - - GitHub will show you a preview of the app configuration - Confirm the app name (you can customize it) - Click "Create GitHub App" - The app will be created with all required permissions automatically configured 3. **Generate and download a private key:** - - After creating the app, you'll be redirected to the app settings - Scroll down to "Private keys" - Click "Generate a private key" @@ -64,7 +60,6 @@ The fastest way to create a custom GitHub App is using our pre-configured manife If you prefer to configure the app manually or need custom permissions: 1. **Create a new GitHub App:** - - Go to https://github.com/settings/apps (for personal apps) or your organization's settings - Click "New GitHub App" - Configure the app with these minimum permissions: @@ -77,19 +72,16 @@ If you prefer to configure the app manually or need custom permissions: - Create the app 2. **Generate and download a private key:** - - After creating the app, scroll down to "Private keys" - Click "Generate a private key" - Download the `.pem` file (keep this secure!) 3. **Install the app on your repository:** - - Go to the app's settings page - Click "Install App" - Select the repositories where you want to use Claude 4. **Add the app credentials to your repository secrets:** - - Go to your repository's Settings → Secrets and variables → Actions - Add these secrets: - `APP_ID`: Your GitHub App's ID (found in the app settings) @@ -138,7 +130,6 @@ For more information on creating GitHub Apps, see the [GitHub documentation](htt To securely use your Anthropic API key: 1. Add your API key as a repository secret: - - Go to your repository's Settings - Navigate to "Secrets and variables" → "Actions" - Click "New repository secret" diff --git a/portable-workflows/.github/workflows/claude-agent.yml b/portable-workflows/.github/workflows/claude-agent.yml new file mode 100644 index 000000000..5cc793784 --- /dev/null +++ b/portable-workflows/.github/workflows/claude-agent.yml @@ -0,0 +1,43 @@ +name: Claude Agent + +# Agent mode: Run Claude with a custom prompt via workflow_dispatch +# Trigger manually from the GitHub Actions UI or via API +on: + workflow_dispatch: + inputs: + prompt: + description: "The task for Claude to perform" + required: true + type: string + branch: + description: "Branch to run on (default: main)" + required: false + default: "main" + type: string + +jobs: + agent: + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + issues: write + id-token: write + actions: read + steps: + - name: Checkout repository + uses: actions/checkout@v6 + with: + ref: ${{ inputs.branch }} + fetch-depth: 1 + + - name: Run Claude Agent + id: claude + uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + prompt: ${{ inputs.prompt }} + + # Optional: Configure allowed tools for the agent + # claude_args: | + # --allowedTools "Bash(npm install),Bash(npm run build),Bash(npm run test:*)" diff --git a/portable-workflows/.github/workflows/claude-review.yml b/portable-workflows/.github/workflows/claude-review.yml new file mode 100644 index 000000000..8734ecbb9 --- /dev/null +++ b/portable-workflows/.github/workflows/claude-review.yml @@ -0,0 +1,43 @@ +name: PR Review + +# Automatically reviews PRs when opened, updated, or reopened +on: + pull_request: + types: [opened, synchronize, ready_for_review, reopened] + +jobs: + review: + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + id-token: write + steps: + - name: Checkout repository + uses: actions/checkout@v6 + with: + fetch-depth: 1 + + - name: PR Review + uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + + # Enable progress tracking for visual feedback + track_progress: true + + prompt: | + REPO: ${{ github.repository }} + PR NUMBER: ${{ github.event.pull_request.number }} + + Perform a thorough code review focusing on: + + 1. **Code Quality** - Clean code, error handling, readability + 2. **Security** - Vulnerabilities, input validation, auth logic + 3. **Performance** - Bottlenecks, inefficient queries, resource issues + 4. **Testing** - Adequate coverage, edge cases, missing scenarios + + Provide inline comments for specific issues and a top-level summary. + + claude_args: | + --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)" diff --git a/portable-workflows/.github/workflows/claude.yml b/portable-workflows/.github/workflows/claude.yml new file mode 100644 index 000000000..32a9a59ab --- /dev/null +++ b/portable-workflows/.github/workflows/claude.yml @@ -0,0 +1,50 @@ +name: Claude Code + +# Tag mode: Claude responds to @claude mentions on issues and PRs +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + issues: + types: [opened, assigned] + pull_request_review: + types: [submitted] + +jobs: + claude: + if: | + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || + (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + issues: write + id-token: write + actions: read # Required for Claude to read CI results on PRs + steps: + - name: Checkout repository + uses: actions/checkout@v6 + with: + fetch-depth: 1 + + - name: Run Claude Code + id: claude + uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + + # Optional: Customize the trigger phrase (default: @claude) + # trigger_phrase: "/claude" + + # Optional: Trigger when specific user is assigned to an issue + # assignee_trigger: "claude-bot" + + # Optional: Configure Claude's behavior with CLI arguments + # claude_args: | + # --model claude-opus-4-6 + # --max-turns 10 + # --allowedTools "Bash(npm install),Bash(npm run build),Bash(npm run test:*),Bash(npm run lint:*)" diff --git a/portable-workflows/SETUP.md b/portable-workflows/SETUP.md new file mode 100644 index 000000000..aa4706734 --- /dev/null +++ b/portable-workflows/SETUP.md @@ -0,0 +1,34 @@ +# Claude Code Action - Setup Guide + +## Prerequisites + +1. An Anthropic API key (get one at https://console.anthropic.com) + +## Installation + +1. Copy the `.github/workflows/` folder into your repository root +2. Add the `ANTHROPIC_API_KEY` secret to your repository: + - Go to **Settings > Secrets and variables > Actions** + - Click **New repository secret** + - Name: `ANTHROPIC_API_KEY` + - Value: your Anthropic API key + +## Included Workflows + +| File | Mode | Trigger | What it does | +| ------------------- | ----- | ------------------------------- | --------------------------------------------------------------- | +| `claude.yml` | Tag | `@claude` mention on issues/PRs | Claude responds to mentions, can write code and create branches | +| `claude-review.yml` | Agent | PR opened/updated | Automatic code review with inline comments | +| `claude-agent.yml` | Agent | Manual (workflow_dispatch) | Run any task via GitHub Actions UI | + +## Usage + +- **Tag mode**: Comment `@claude fix this bug` on any issue or PR +- **PR review**: Automatic on every new/updated PR +- **Agent mode**: Go to Actions > Claude Agent > Run workflow, enter a prompt + +## Customization + +- Edit `claude_args` in each workflow to restrict/allow specific tools +- Add `--model claude-opus-4-6` to `claude_args` to use a specific model +- Set `trigger_phrase` to change from `@claude` to something else