feat(docs): ✨ update README and action.yml with permissions guidance

* add permissions block example for GitHub Actions
* clarify usage of `github-token` and Personal Access Token (PAT) in action.yml
* bump version in package.json to 1.0.6

Author: mberbero

README.md

@@ -28,6 +28,10 @@ on:
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    # Recommended: grant the job the permissions needed to post comments or update releases
+    permissions:
+      contents: write
+      issues: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -43,5 +47,25 @@ jobs:
           base-url: ${{ secrets.COSWARM_API_URL }}
           token: ${{ secrets.COSWARM_DEPLOY_TOKEN }}
           image: redis:alpine
+          # Optional: override the token used to post comments/issues/releases.
+          # Defaults to the automatically provided GITHUB_TOKEN when omitted.
           github-token: ${{ github.token }}
 ```
+
+## Permissions and tokens
+
+- **Prefer granting job permissions**: If the workflow runs in-repo, add a `permissions` block to the job to allow write operations (shown above).
+- **Forked PRs limitation**: Workflows triggered from forks do not have access to secrets and receive limited permissions; write operations (comments/releases) will fail in that context.
+- **Use a PAT when needed**: To guarantee write access (or to operate across repos), create a Personal Access Token with the minimal scopes you need (for release/commenting `repo` or `public_repo`) and pass it via the `github-token` input as a repository secret.
+
+Example with a PAT (stored as `PERSONAL_GITHUB_TOKEN`):
+
+```yaml
+- name: Coswarm Deploy
+  uses: kintsdev/coswarm-deploy@latest
+  with:
+    base-url: ${{ secrets.COSWARM_API_URL }}
+    token: ${{ secrets.COSWARM_DEPLOY_TOKEN }}
+    image: redis:alpine
+    github-token: ${{ secrets.PERSONAL_GITHUB_TOKEN }}
+```

action.yml

@@ -12,7 +12,7 @@ inputs:
     description: "Coswarm API base URL. Must be provided explicitly."
     required: true
   github-token:
-    description: "Personal access token to create an issue when the deploy fails. Defaults to GITHUB_TOKEN."
+    description: "GitHub token used to create issues/comments and update releases. Defaults to GITHUB_TOKEN.\n\nIf you rely on the default GITHUB_TOKEN, ensure the calling workflow grants the action write permissions (for example `contents: write` and `issues: write`). For workflows triggered from forks, secrets and write permissions may be unavailable — in that case provide a Personal Access Token (PAT) via this input with minimal required scopes (e.g. `repo`/`public_repo`)."
     required: false
 outputs:
   response:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "coswarm-deploy-action",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "GitHub Action that triggers Coswarm deployments and files issues on failure.",
   "main": "build/index.js",
   "scripts": {