Documenting...

Author: rmottanet

README.md

@@ -1 +1,108 @@
-# pr-spark
+# 🚀 PR Spark
+
+**PR Spark** is a GitHub Action that **automatically creates Pull Requests** between branches using the GitHub API.  
+It helps you **streamline workflows**, keep branches in sync, and speed up your CI/CD pipelines.  
+
+✨ Perfect for:  
+- Automating routine Pull Requests  
+- Keeping feature branches up to date  
+- Enforcing consistent workflows  
+- Saving time in collaborative projects  
+
+
+-----
+
+### How to Use
+
+To use this Action in your workflow, add the following step to your `.yml` file:
+
+```yaml
+- name: Create Pull Request
+  uses: ws2git/pr-spark@v1
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    title: 'Title of your Pull Request'
+    body: 'Detailed description of the PR.'
+    source-branch: 'my-source-branch'
+    dest-branch: 'main'
+```
+
+
+### Inputs
+
+The following inputs can be used to configure the Action.
+
+| Input Name | Required | Description | Example |
+| :--- | :---: | :--- | :--- |
+| `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 }}` |
+| `title` | **Yes** | The title of the Pull Request. Can be a static string or a dynamic variable. | `"Project Deploy"` |
+| `body` | No | The description (body) of the Pull Request. Supports Markdown for formatting. | `"This PR contains the new features..."` |
+| `source-branch` | **Yes** | The name of the source branch (the branch where changes were made). | `"feature/new-feature"` |
+| `dest-branch` | **Yes** | The name of the destination branch (the branch where the PR will be opened). | `"main"` |
+
+
+### Outputs
+
+The Action generates one output that can be used in subsequent steps of your workflow.
+
+| Output Name | Description |
+| :--- | :--- |
+| `pull-request-url` | The full URL of the created Pull Request. |
+
+
+**Output Usage Example:**
+
+```yaml
+- name: Log PR URL
+  run: echo "Created PR URL: ${{ steps.your-action-step-id.outputs.pull-request-url }}"
+```
+
+Make sure to replace `your-action-step-id` with the `id` of the step where you call the Action.
+
+
+### Full Workflow Example
+
+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.
+
+```yaml
+name: Example Workflow
+
+on:
+  push:
+    branches:
+      - develop
+
+jobs:
+  create-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Generate date for the title
+        id: set-date
+        run: |
+          # Gets the current date in 'dd-mm-yyyy' format
+          CURRENT_DATE=$(date +"%d-%m-%Y")
+          echo "date=$CURRENT_DATE" >> "$GITHUB_OUTPUT"
+
+      - name: Create Pull Request
+        id: create-pr
+        uses: ws2git/pr-spark@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          # The title is now dynamic, using the output variable from the previous step
+          title: "Deploy ${{ steps.set-date.outputs.date }}"
+          body: "This is a test PR generated by the custom action."
+          source-branch: "develop"
+          dest-branch: "main"
+
+      - name: Display Created PR URL
+        run: echo "Created PR URL: ${{ steps.create-pr.outputs.pull-request-url }}"
+```
+
+-----
+
+### Support
+
+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.