Skip to content

Commit 1008411

Browse files
rmottanetrmottanet
authored
Architectural Refactoring (#3)
* feat(service): add dedicated githubservice for pr creation - introduces src/services/github.service.ts to encapsulate the octokit logic for creating a pull request. - this decouples the core business logic from input handling and orchestration, adhering to the project's modular architecture standards * feat(config): implement configmanager for input handling and validation - moves input reading and validation logic into src/config.ts. - this ensures all configuration and necessary context variables (inputs, owner, repo) are centralized and validated before execution, preventing logic leaks into the main orchestrator. * refactor(main): convert entry point to pure orchestrator - renames the main action file to src/main.ts and refactors it to act as a clear orchestrator. - the file now exclusively handles the flow: configmanager -> githubservice -> output setting, enforcing separation of concerns. * build(package): update compiler entry point to src/main.ts - adjusts package.json to point to the new main file (src/main.ts) for compilation, reflecting the modular file structure. * feat(action): add owner and repo inputs to action.yml - introduces 'owner' and 'repo' as required inputs to enable cross-repository pull request creation. this aligns the action with the established project pattern and ensures multi-repo flexibility. * chore(dist): regenerate distribution artifact - compiles the modularized source code into the final distribution artifact in /dist, ready for deployment/release. * documenting...
1 parent b1a1376 commit 1008411

File tree

8 files changed

+222
-32049
lines changed

8 files changed

+222
-32049
lines changed

‎README.md‎

Lines changed: 94 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,123 @@
1-
# 🚀 PR Spark
1+
# PR Spark
22

3-
**PR Spark** is a GitHub Action that **automatically creates Pull Requests** between branches using the GitHub API.
4-
It helps you **streamline workflows**, keep branches in sync, and speed up your CI/CD pipelines.
3+
Automatically create pull requests between branches using GitHub's API for workflows and automation.
4+
This GitHub Action is useful for teams who want to automate PR creation in CI/CD pipelines, branch synchronization, or cross-repository workflows.
55

6-
✨ Perfect for:
7-
- Automating routine Pull Requests
8-
- Keeping feature branches up to date
9-
- Enforcing consistent workflows
10-
- Saving time in collaborative projects
6+
---
117

8+
## ✨ Features
129

13-
-----
10+
- **Automated PR Creation**: Create pull requests programmatically between any branches
11+
- **Cross-Repository Support**: Create PRs in different repositories within the same organization
12+
- **Flexible Configuration**: Customizable PR title, body, source, and destination branches
13+
- **Powered by GitHub API**: Uses official GitHub REST API for reliable PR management
14+
- **Organization-wide**: Can be used across any repository with proper permissions
1415

15-
### How to Use
16+
## 🛠️ Usage
1617

17-
To use this Action in your workflow, add the following step to your `.yml` file:
18-
19-
```yaml
20-
- name: Create Pull Request
21-
uses: ws2git/pr-spark@v1
22-
with:
23-
github-token: ${{ secrets.GITHUB_TOKEN }}
24-
title: 'Title of your Pull Request'
25-
body: 'Detailed description of the PR.'
26-
source-branch: 'my-source-branch'
27-
dest-branch: 'main'
28-
```
18+
### 1. **Prerequisites**
2919

20+
- Your workflow **must pass the necessary inputs** to this action
21+
- The GitHub token must have `repo` permissions to create pull requests
22+
- Source and destination branches must exist in the target repository
3023

31-
### Inputs
24+
### 2. **Example Workflow Integration**
3225

33-
The following inputs can be used to configure the Action.
26+
```yaml
27+
name: Quick PR Spark Test
3428

35-
| Input Name | Required | Description | Example |
36-
| :--- | :---: | :--- | :--- |
37-
| `github-token` | **Yes** | The GitHub token used for API authentication. The default `secrets.GITHUB_TOKEN` already has the necessary permissions to create a Pull Request. | `${{ secrets.GITHUB_TOKEN }}` |
38-
| `title` | **Yes** | The title of the Pull Request. Can be a static string or a dynamic variable. | `"Project Deploy"` |
39-
| `body` | No | The description (body) of the Pull Request. Supports Markdown for formatting. | `"This PR contains the new features..."` |
40-
| `source-branch` | **Yes** | The name of the source branch (the branch where changes were made). | `"feature/new-feature"` |
41-
| `dest-branch` | **Yes** | The name of the destination branch (the branch where the PR will be opened). | `"main"` |
29+
on: [workflow_dispatch]
4230

31+
jobs:
32+
quick-test:
33+
runs-on: ubuntu-latest
34+
steps:
35+
- uses: actions/checkout@v4
36+
37+
- name: Create test PR
38+
uses: ws2git/pr-spark@v3
39+
with:
40+
github-token: ${{ secrets.GITHUB_TOKEN }}
41+
owner: ${{ github.repository_owner }}
42+
repo: ${{ github.event.repository.name }}
43+
title: "Quick Test PR"
44+
body: "Testing PR Spark action functionality"
45+
source-branch: "develop" # Adjust according to your branches.
46+
dest-branch: "main" # Adjust according to your branches.
47+
```
4348
44-
### Outputs
49+
## 📥 Inputs
50+
51+
| Name | Required | Description |
52+
|---|---|---|
53+
| `github-token` | Yes | GitHub token for authentication (requires repo scope) |
54+
| `owner` | Yes | The owner/organization of the target repository |
55+
| `repo` | Yes | The name of the target repository |
56+
| `title` | Yes | Pull Request title |
57+
| `body` | No | Pull Request body/description |
58+
| `source-branch` | Yes | The branch from which the PR will be opened |
59+
| `dest-branch` | Yes | The PR target branch |
60+
61+
## 📤 Outputs
62+
63+
| Name | Description |
64+
|---|---|
65+
| `pull-request-url` | URL of the created pull request |
66+
67+
## ⚙️ How It Works
68+
69+
This action uses the GitHub REST API via Octokit to create pull requests. It validates all inputs, checks for branch conflicts, and creates the PR with the specified parameters.
70+
71+
**Core logic:**
72+
```typescript
73+
// Creates PR using GitHub API
74+
await octokit.rest.pulls.create({
75+
owner,
76+
repo,
77+
title,
78+
head: sourceBranch,
79+
base: destBranch,
80+
body
81+
});
82+
```
4583

46-
The Action generates one output that can be used in subsequent steps of your workflow.
84+
If source and destination branches are the same, or if required parameters are missing, the action fails with descriptive error messages.
4785

48-
| Output Name | Description |
49-
| :--- | :--- |
50-
| `pull-request-url` | The full URL of the created Pull Request. |
86+
## 🛡️ Security and Authentication
5187

88+
This Action uses the **GitHub REST API** with a provided token for authentication.
5289

53-
**Output Usage Example:**
90+
**Recommended**: For operations within the current repository, use the default **`${{ secrets.GITHUB_TOKEN }}`**:
5491

5592
```yaml
56-
- name: Log PR URL
57-
run: echo "Created PR URL: ${{ steps.your-action-step-id.outputs.pull-request-url }}"
93+
with:
94+
github-token: ${{ secrets.GITHUB_TOKEN }}
5895
```
5996

60-
Make sure to replace `your-action-step-id` with the `id` of the step where you call the Action.
97+
**Cross-Repository Operations**: For creating PRs in different repositories, use a **PAT** (Personal Access Token) with `repo` scope stored as a secret:
6198

99+
```yaml
100+
with:
101+
github-token: ${{ secrets.MY_PAT_WITH_REPO_SCOPE }}
102+
```
62103

63-
### Full Workflow Example
104+
**Never expose tokens in plain text.**
64105

65-
This is an example of a complete workflow that uses the Action to open a PR. It demonstrates how to use the Action dynamically by creating a title with the current date.
106+
## 📌 Notes
66107

67-
```yaml
68-
name: Example Workflow
108+
⚠️ **Important Considerations:**
69109

70-
on:
71-
push:
72-
branches:
73-
- develop
110+
- The source and destination branches must exist in the target repository
111+
- For cross-repository PRs, the token must have access to both source and target repositories
112+
- If a PR between the same branches already exists, the action will fail
113+
- Branch names are validated for proper Git format
74114

75-
jobs:
76-
create-pr:
77-
runs-on: ubuntu-latest
78-
steps:
79-
- name: Checkout code
80-
uses: actions/checkout@v4
81-
82-
- name: Generate date for the title
83-
id: set-date
84-
run: |
85-
# Gets the current date in 'dd-mm-yyyy' format
86-
CURRENT_DATE=$(date +"%d-%m-%Y")
87-
echo "date=$CURRENT_DATE" >> "$GITHUB_OUTPUT"
88-
89-
- name: Create Pull Request
90-
id: create-pr
91-
uses: ws2git/pr-spark@v1
92-
with:
93-
github-token: ${{ secrets.GITHUB_TOKEN }}
94-
# The title is now dynamic, using the output variable from the previous step
95-
title: "Deploy ${{ steps.set-date.outputs.date }}"
96-
body: "This is a test PR generated by the custom action."
97-
source-branch: "develop"
98-
dest-branch: "main"
99-
100-
- name: Display Created PR URL
101-
run: echo "Created PR URL: ${{ steps.create-pr.outputs.pull-request-url }}"
102-
```
115+
## 🔗 Related Documentation
103116

104-
-----
117+
- [GitHub REST API - Pull Requests](https://docs.github.com/en/rest/pulls/pulls?apiVersion=2022-11-28#create-a-pull-request)
118+
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
119+
- [Octokit.js Library](https://github.com/octokit/octokit.js)
105120

106-
### Support
121+
## ❓ Support
107122

108-
If you find any issues or have suggestions for improvements, feel free to open an [Issue](https://github.com/ws2git/pr-spark/issues) in this repository.
123+
If you find a bug or have a question, [open an issue](https://github.com/ws2git/pr-spark/issues).

‎action.yml‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,11 @@ branding:
55
icon: 'git-pull-request'
66
color: 'orange'
77
inputs:
8-
github-token:
9-
description: 'GitHub token for authentication'
8+
owner:
9+
description: 'The owner/organization of the target repository'
10+
required: true
11+
repo:
12+
description: 'The name of the target repository'
1013
required: true
1114
title:
1215
description: 'Pull Request Title'
@@ -20,7 +23,10 @@ inputs:
2023
dest-branch:
2124
description: 'The PR target branch'
2225
required: true
23-
26+
github-token:
27+
description: 'GitHub token for authentication'
28+
required: true
29+
2430
outputs:
2531
pull-request-url:
2632
description: 'Created Pull Request URL'

0 commit comments

Comments
 (0)