Skip to content

Commit f2d52cf

Browse files
rmottanetrmottanet
authored
Introducing... (#1)
* feat(core): implement base project structure - Add TypeScript configuration with strict type checking - Set up GitHub Actions workflow foundation - Configure build system with NCC compiler - Establish monorepo-like module architecture - Add core dependencies (@actions/core, @actions/github) Technical Details: - tsconfig: ES2020 target, CommonJS module system - package.json: Node20 runtime, Apache 2.0 license - src/ structure: main.ts (orchestrator), config.ts, services/ * feat(config): implement configuration management layer - Create ConfigManager class with SRP compliance - Implement ActionInputs interface with readonly properties - Add input validation with comprehensive error handling - Support PR URL parsing with regex validation - Type-safe event validation (COMMENT|APPROVE|REQUEST_CHANGES) Technical Implementation: - parsePullRequestUrl(): extracts owner/repo/pullNumber from URL - validateEvent(): ensures event type safety - validate(): checks input constraints and business rules - Immutable input interface prevents side effects * feat(github): implement GitHub API service layer - Create GitHubService class with Octokit client - Implement reviewCode() method with proper error handling - Add PR metadata retrieval for latest commit SHA - Support all GitHub review events (comment/approve/request_changes) - Comprehensive error wrapping for API failures API Integration: - octokit.rest.pulls.get(): fetch PR metadata - octokit.rest.pulls.createReview(): submit code review - Automatic commit SHA resolution from PR head - Typed Octokit client for better intellisense * feat(orchestration): implement main workflow coordinator - Create main.ts as pure workflow orchestrator - Implement dependency injection pattern - Add comprehensive error handling with type guards - Structured logging with meaningful progress indicators - Output management for downstream actions Orchestration Pattern: - ConfigManager.getInputs(): input validation - GitHubService injection: service layer isolation - Sequential workflow: validate → execute → output - Error type discrimination: Error vs unknown * feat(action): define action metadata and interface - Create action.yml with input specifications - Document all parameters with descriptions and requirements - Configure Node20 runtime environment - Define input validation rules in metadata Action Interface: - pull_request_url: full PR URL for context - event: review type with case-insensitive handling - body: review message content - github-token: authentication token - Required fields enforcement * chore(build): optimize build and distribution - Configure NCC for single-file distribution - Add source maps for debugging - Include license files in distribution - Optimize bundle size with tree shaking - Add build validation scripts Build Improvements: - ncc build with source maps enabled - License aggregation for compliance - Pre-publish validation hooks - Size optimization for faster GitHub Actions * documenting...
1 parent 2930a7c commit f2d52cf

File tree

9 files changed

+713
-2
lines changed

9 files changed

+713
-2
lines changed

‎README.md‎

Lines changed: 157 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,158 @@
1-
# coude-scout
1+
# Code Scout
22

3-
Code Scout: A GitHub Action for automated code review—approve PRs, comment, or request changes using the GitHub REST API for smarter CI workflows.
3+
Automated code review Action to programmatically approve PRs, comment, or request changes using GitHub's API.
4+
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.
5+
6+
---
7+
8+
## ✨ Features
9+
10+
- **Programmatic Code Reviews**: Automatically submit reviews with comments, approvals, or change requests.
11+
- **Simple Integration**: One-step usage in any workflow with minimal configuration.
12+
- **Powered by GitHub API**: Uses Octokit for secure pull request management and review operations.
13+
- **Organization-wide**: Can be used across any repository with proper permissions.
14+
- **Type-Safe**: Built with TypeScript for reliability and better developer experience.
15+
16+
## 🛠️ Usage
17+
18+
### 1. **Prerequisites**
19+
20+
- Your workflow **must pass the necessary inputs** to this action.
21+
- This action requires **Node 20** runtime (included in GitHub-hosted runners).
22+
- The GitHub token must have **`pull-requests: write`** permissions to submit reviews.
23+
24+
### 2. **Example Workflow Integration**
25+
26+
```yaml
27+
name: Automated Code Review
28+
29+
on:
30+
pull_request:
31+
types: [opened, synchronize]
32+
branches: [main, master]
33+
34+
jobs:
35+
code-review:
36+
runs-on: ubuntu-latest
37+
permissions:
38+
contents: read
39+
pull-requests: write
40+
steps:
41+
- name: Submit Code Review
42+
uses: ws2git/code-scout@v1
43+
with:
44+
pull_request_url: ${{ github.event.pull_request.html_url }}
45+
event: 'comment'
46+
body: '🤖 Automated review: Code structure looks good!'
47+
github-token: ${{ github.token }}
48+
```
49+
50+
### 3. **Manual Trigger Example**
51+
52+
```yaml
53+
name: Manual Code Review
54+
55+
on:
56+
workflow_dispatch:
57+
inputs:
58+
pull_request_url:
59+
description: 'PR URL to review'
60+
required: true
61+
review_type:
62+
description: 'Review type'
63+
required: true
64+
type: choice
65+
options: [comment, approve, request_changes]
66+
review_message:
67+
description: 'Review message'
68+
required: true
69+
70+
jobs:
71+
manual-review:
72+
runs-on: ubuntu-latest
73+
permissions:
74+
contents: read
75+
pull-requests: write
76+
steps:
77+
- name: Execute Manual Review
78+
uses: ws2git/code-scout@v1
79+
with:
80+
pull_request_url: ${{ github.event.inputs.pull_request_url }}
81+
event: ${{ github.event.inputs.review_type }}
82+
body: ${{ github.event.inputs.review_message }}
83+
github-token: ${{ secrets.GITHUB_TOKEN }}
84+
```
85+
86+
## 📥 Inputs
87+
88+
| Name | Required | Description |
89+
|---|---|---|
90+
| `pull_request_url` | Yes | Full URL of the pull request to review (e.g., `https://github.com/owner/repo/pull/123`) |
91+
| `event` | Yes | Type of review: `comment`, `approve`, or `request_changes` |
92+
| `body` | Yes | The review message content (supports Markdown) |
93+
| `github-token` | Yes | GitHub token with pull request write permissions |
94+
95+
## ⚙️ How It Works
96+
97+
Internally, this action uses the GitHub Octokit REST API to submit code reviews programmatically.
98+
99+
**Technical workflow:**
100+
1. **Parse PR URL**: Extracts owner, repository, and pull request number from the URL
101+
2. **Validate Inputs**: Ensures all parameters meet GitHub API requirements
102+
3. **Fetch PR Data**: Retrieves the latest commit SHA from the pull request
103+
4. **Submit Review**: Creates a review with the specified event type and message
104+
105+
**Core implementation:**
106+
```typescript
107+
// Submit review via GitHub API
108+
await octokit.rest.pulls.createReview({
109+
owner,
110+
repo,
111+
pull_number: pullNumber,
112+
commit_id: commitSha,
113+
body: reviewMessage,
114+
event: reviewType,
115+
});
116+
```
117+
118+
If any required parameter is missing or invalid, the action fails with descriptive error messages.
119+
120+
## 🛡️ Security and Authentication
121+
122+
This Action uses the **GitHub Token** to authenticate with the GitHub REST API and requires write permissions for pull requests.
123+
124+
**Recommended**: For repositories within the same organization, use the default **`${{ github.token }}`**:
125+
126+
```yaml
127+
with:
128+
github-token: ${{ github.token }}
129+
```
130+
131+
**Cross-Repository Reviews**: For reviewing pull requests in external repositories, use a **PAT** (Personal Access Token) with `repo` scope:
132+
133+
```yaml
134+
with:
135+
github-token: ${{ secrets.CODE_REVIEW_PAT }}
136+
```
137+
138+
**Never expose tokens in plain text or commit them to version control.**
139+
140+
## 📌 Notes
141+
142+
⚠️ **Important Configuration Notes:**
143+
144+
- **Permissions**: Ensure your workflow has `pull-requests: write` permission
145+
- **Event Types**: Use lowercase for event types in workflows (`comment`, `approve`, `request_changes`)
146+
- **Message Length**: Review bodies are limited to 65,536 characters
147+
- **Rate Limiting**: Be mindful of GitHub API rate limits when using frequently
148+
149+
## 🔗 Related Documentation
150+
151+
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
152+
- [GitHub REST API - Pull Request Reviews](https://docs.github.com/en/rest/pulls/reviews)
153+
- [Octokit Documentation](https://octokit.github.io/rest.js/)
154+
- [TypeScript Configuration](https://www.typescriptlang.org/docs)
155+
156+
## ❓ Support
157+
158+
If you find a bug or have a question, [open an issue](https://github.com/ws2git/code-scout/issues).

‎action.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: 'Code Scout'
2+
description: 'Automated code review Action to approve PRs, comment, or request changes.'
3+
author: 'rmottanet'
4+
branding:
5+
icon: 'git-pull-request'
6+
color: 'orange'
7+
inputs:
8+
pull_request_url:
9+
description: 'URL completa da pull request'
10+
required: true
11+
event:
12+
description: 'Tipo de review (comment, approve, request_changes)'
13+
required: true
14+
body:
15+
description: 'Mensagem do review'
16+
required: true
17+
github-token:
18+
description: 'GitHub token for authentication'
19+
required: true
20+
21+
runs:
22+
using: 'node20'
23+
main: 'dist/index.js'

‎dist/index.js‎

Lines changed: 3 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)