claude-intern 1.2.1 → 1.3.1

package/.env.sample

@@ -30,13 +30,35 @@ CLAUDE_CLI_PATH=claude
 # VERBOSE=true
 
 # Optional: Pull Request Integration
-# GitHub personal access token for creating pull requests
-# Create one at: https://github.com/settings/tokens (needs 'repo' scope)
+#
+# Option 1: GitHub Personal Access Token (for individual users)
+# Create at: https://github.com/settings/tokens
+# Required permissions:
+#   - Classic token: 'repo' scope (or 'public_repo' for public repos only)
+#   - Fine-grained token (recommended): 'Pull requests: Read and write' + 'Contents: Read'
 # GITHUB_TOKEN=your-github-token-here
+#
+# Option 2: GitHub App Authentication (for organizations)
+# Each organization creates their own GitHub App for centralized control.
+# Create at: https://github.com/settings/apps (or your org's settings)
+# Required App permissions:
+#   - Repository permissions:
+#     - Contents: Read (to check branches)
+#     - Pull requests: Read and write (to create PRs)
+# After creating the App, generate a private key and install the App on your repositories.
+#
+# GITHUB_APP_ID=123456
+# Private key can be provided as a file path:
+# GITHUB_APP_PRIVATE_KEY_PATH=/path/to/your-app.private-key.pem
+# Or as base64-encoded content (useful for CI/CD environments):
+# To encode: base64 -i your-key.pem (macOS) or base64 -w 0 your-key.pem (Linux)
+# GITHUB_APP_PRIVATE_KEY_BASE64=LS0tLS1CRUdJTi4uLg==
+#
+# Note: If both GITHUB_TOKEN and GitHub App credentials are set, GITHUB_TOKEN takes precedence.
 
-# Bitbucket app password for creating pull requests  
-# Create one at: https://bitbucket.org/account/settings/app-passwords/
-# Needs 'Repositories: Write' permission
+# Bitbucket app password for creating pull requests
+# Create at: https://bitbucket.org/account/settings/app-passwords/
+# Required permissions: 'Repositories: Write'
 # BITBUCKET_TOKEN=your-bitbucket-app-password-here
 
 # Note: Bitbucket workspace is automatically detected from your git remote URL

package/README.md

@@ -96,9 +96,23 @@ Update your `.env` file with your JIRA details:
    - `JIRA_EMAIL`: Your JIRA email address
    - `JIRA_API_TOKEN`: Your JIRA API token (create one at https://id.atlassian.com/manage-profile/security/api-tokens)
 
-   Optional PR integration:
+   Optional PR integration (choose one):
+
+   **Option 1: GitHub Personal Access Token** (for individual users)
    - `GITHUB_TOKEN`: GitHub personal access token for creating pull requests
+     - **Classic token**: Requires `repo` scope
+     - **Fine-grained token** (recommended): Requires `Pull requests: Read and write` and `Contents: Read` permissions
+     - Create at: https://github.com/settings/tokens
+
+   **Option 2: GitHub App Authentication** (for organizations)
+   - `GITHUB_APP_ID`: Your GitHub App's ID
+   - `GITHUB_APP_PRIVATE_KEY_PATH`: Path to your App's private key file
+   - See [GitHub App Setup](#github-app-setup) section below for detailed instructions
+
+   **Bitbucket:**
    - `BITBUCKET_TOKEN`: Bitbucket app password for creating pull requests
+     - Requires `Repositories: Write` permission
+     - Create at: https://bitbucket.org/account/settings/app-passwords/
 
    The `.env.sample` file includes helpful comments and optional configuration options.
 
@@ -128,6 +142,63 @@ The `.claude-intern/settings.json` file allows you to configure project-specific
 
 **Example:** If you work with multiple JIRA projects that have different workflows (e.g., "PROJ" uses "In Review" but "ABC" uses "Code Review"), configure each project's status in `settings.json`.
 
+### GitHub App Setup
+
+For organizations that want centralized control over PR creation, you can configure a GitHub App instead of using individual personal access tokens.
+
+**Benefits of GitHub App authentication:**
+- No individual tokens needed - the App authenticates itself
+- Fine-grained permissions - only pull request and content read access
+- Centralized control - organization admins manage the App installation
+- Audit trail - all actions show as coming from the App, not individual users
+
+**Setup Steps:**
+
+1. **Create a GitHub App:**
+   - Go to your organization's Settings → Developer settings → GitHub Apps → New GitHub App
+   - Or for personal account: https://github.com/settings/apps
+   - Fill in the required fields:
+     - **App name:** e.g., "Claude Intern Bot" (must be unique across GitHub)
+     - **Homepage URL:** Your project URL or a placeholder
+     - **Webhook:** Uncheck "Active" (not needed)
+   - Set **Repository permissions:**
+     - **Contents:** Read (to check branches)
+     - **Pull requests:** Read and write (to create PRs)
+   - Click "Create GitHub App"
+
+2. **Generate a Private Key:**
+   - On your App's settings page, scroll to "Private keys"
+   - Click "Generate a private key"
+   - Save the downloaded `.pem` file securely
+
+3. **Install the App:**
+   - Go to your App's page → "Install App"
+   - Select the organization/account and repositories where you want to use it
+
+4. **Configure claude-intern:**
+   Add to your `.claude-intern/.env`:
+   ```bash
+   GITHUB_APP_ID=123456  # Your App's ID (shown on the App's settings page)
+   GITHUB_APP_PRIVATE_KEY_PATH=/secure/path/to/your-app.private-key.pem
+   ```
+
+   Or for CI/CD environments, use base64-encoded key:
+   ```bash
+   GITHUB_APP_ID=123456
+   GITHUB_APP_PRIVATE_KEY_BASE64=LS0tLS1CRUdJTi4uLg==
+   ```
+
+   To encode your key:
+   ```bash
+   # macOS
+   base64 -i your-app.private-key.pem
+
+   # Linux
+   base64 -w 0 your-app.private-key.pem
+   ```
+
+**Note:** If both `GITHUB_TOKEN` and GitHub App credentials are configured, `GITHUB_TOKEN` takes precedence.
+
 ## Usage
 
 ### Single Task Processing
@@ -169,6 +240,12 @@ claude-intern TASK-123 --create-pr
 # Create pull request targeting specific branch
 claude-intern TASK-123 --create-pr --pr-target-branch develop
 
+# Auto-detect target branch from JIRA task description
+# Simply add "Target branch: <branch-name>" to your task description
+# Patterns supported: "Target branch:", "Base branch:", "PR target:"
+claude-intern TASK-123 --create-pr
+# (will use branch specified in task description, or fall back to --pr-target-branch)
+
 # Testing options - skip ALL JIRA comments (feasibility + implementation)
 claude-intern TASK-123 --skip-jira-comments