Code Scout

Automated code review Action to programmatically approve PRs, comment, or request changes using GitHub's API. This GitHub Action is useful for teams who want to automate code review processes, enforce quality gates, and provide consistent feedback across all pull requests.

---

✨ Features

• Programmatic Code Reviews: Automatically submit reviews with comments, approvals, or change requests.
• Simple Integration: One-step usage in any workflow with minimal configuration.
• Powered by GitHub API: Uses Octokit for secure pull request management and review operations.
• Organization-wide: Can be used across any repository with proper permissions.
• Type-Safe: Built with TypeScript for reliability and better developer experience.

🛠️ Usage

1. Prerequisites

• Your workflow must pass the necessary inputs to this action.
• This action requires Node 20 runtime (included in GitHub-hosted runners).
• The GitHub token must have pull-requests: write permissions to submit reviews.

2. Example Workflow Integration

name: Automated Code Review

on:
  pull_request:
    types: [opened, synchronize]
    branches: [main, master]

jobs:
  code-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: Submit Code Review
        uses: ws2git/code-scout@v1
        with:
          pull_request_url: ${{ github.event.pull_request.html_url }}
          event: 'comment'
          body: '🤖 Automated review: Code structure looks good!'
          github-token: ${{ github.token }}

3. Manual Trigger Example

name: Manual Code Review

on:
  workflow_dispatch:
    inputs:
      pull_request_url:
        description: 'PR URL to review'
        required: true
      review_type:
        description: 'Review type'
        required: true
        type: choice
        options: [comment, approve, request_changes]
      review_message:
        description: 'Review message'
        required: true

jobs:
  manual-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: Execute Manual Review
        uses: ws2git/code-scout@v1
        with:
          pull_request_url: ${{ github.event.inputs.pull_request_url }}
          event: ${{ github.event.inputs.review_type }}
          body: ${{ github.event.inputs.review_message }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

📥 Inputs

Name	Required	Description
pull_request_url	Yes	Full URL of the pull request to review (e.g., https://github.com/owner/repo/pull/123)
event	Yes	Type of review: comment, approve, or request_changes
body	Yes	The review message content (supports Markdown)
github-token	Yes	GitHub token with pull request write permissions

⚙️ How It Works

Internally, this action uses the GitHub Octokit REST API to submit code reviews programmatically.

Technical workflow:

1. Parse PR URL: Extracts owner, repository, and pull request number from the URL
2. Validate Inputs: Ensures all parameters meet GitHub API requirements
3. Fetch PR Data: Retrieves the latest commit SHA from the pull request
4. Submit Review: Creates a review with the specified event type and message

Core implementation:

// Submit review via GitHub API
await octokit.rest.pulls.createReview({
  owner,
  repo,
  pull_number: pullNumber,
  commit_id: commitSha,
  body: reviewMessage,
  event: reviewType,
});

If any required parameter is missing or invalid, the action fails with descriptive error messages.

🛡️ Security and Authentication

This Action uses the GitHub Token to authenticate with the GitHub REST API and requires write permissions for pull requests.

Recommended: For repositories within the same organization, use the default ${{ github.token }}:

with:
  github-token: ${{ github.token }}

Cross-Repository Reviews: For reviewing pull requests in external repositories, use a PAT (Personal Access Token) with repo scope:

with:
  github-token: ${{ secrets.CODE_REVIEW_PAT }}

Never expose tokens in plain text or commit them to version control.

📌 Notes

⚠️ Important Configuration Notes:

• Permissions: Ensure your workflow has pull-requests: write permission
• Event Types: Use lowercase for event types in workflows (comment, approve, request_changes)
• Message Length: Review bodies are limited to 65,536 characters
• Rate Limiting: Be mindful of GitHub API rate limits when using frequently

🔗 Related Documentation

• GitHub Actions Documentation
• GitHub REST API - Pull Request Reviews
• Octokit Documentation
• TypeScript Configuration

❓ Support

If you find a bug or have a question, open an issue.