@logickernel/agileflow 0.20.0 → 0.21.0

package/README.md

@@ -61,6 +61,9 @@ on:
   push:
     branches: [main]
 
+permissions:
+  contents: write
+
 jobs:
   version:
     runs-on: ubuntu-latest
@@ -74,12 +77,10 @@ jobs:
           node-version: '20'
 
       - name: Create version tag
-        env:
-          AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
         run: npx @logickernel/agileflow github
 ```
 
-Requires an `AGILEFLOW_TOKEN` secret — a Personal Access Token with `Contents: Read and write` permission.
+AgileFlow automatically uses the built-in `GITHUB_TOKEN` — no secrets or custom tokens needed. Just grant `contents: write` permission in the workflow. You can also use a [Personal Access Token](./docs/guides/github-actions.md) if your organization restricts `GITHUB_TOKEN` permissions.
 
 ### GitLab CI
 

package/docs/guides/github-actions.md

@@ -4,23 +4,7 @@ Two workflows: one that runs AgileFlow on push to main and creates a version tag
 
 ---
 
-## Step 1: Create an access token
-
-1. Go to **Settings → Developer settings → Personal access tokens → Fine-grained tokens**
-2. Click **Generate new token**
-3. Set:
-   - **Name**: `AgileFlow`
-   - **Repository access**: your repository
-   - **Permissions**: `Contents: Read and write`
-4. Copy the token
-
-## Step 2: Add the token as a secret
-
-1. In your repository: **Settings → Secrets and variables → Actions**
-2. Click **New repository secret**
-3. Name: `AGILEFLOW_TOKEN`, value: your token
-
-## Step 3: Create the versioning workflow
+## Step 1: Create the versioning workflow
 
 `.github/workflows/version.yml`:
 
@@ -30,6 +14,9 @@ on:
   push:
     branches: [main]
 
+permissions:
+  contents: write
+
 jobs:
   version:
     runs-on: ubuntu-latest
@@ -43,14 +30,31 @@ jobs:
           node-version: '20'
 
       - name: Create version tag
-        env:
-          AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
         run: npx @logickernel/agileflow github
 ```
 
+That's it. AgileFlow automatically picks up the `GITHUB_TOKEN` that GitHub Actions provides. The `permissions: contents: write` block grants it permission to create tags.
+
 `fetch-depth: 0` is required — without it, AgileFlow can only see a shallow clone and cannot find the last version tag.
 
-## Step 4: Create the release workflow
+### Using a Personal Access Token instead
+
+If your organization restricts `GITHUB_TOKEN` permissions or you need cross-repository tagging, use a PAT:
+
+1. Go to **Settings → Developer settings → Personal access tokens → Fine-grained tokens**
+2. Click **Generate new token**
+3. Set:
+   - **Name**: `AgileFlow`
+   - **Repository access**: your repository
+   - **Permissions**: `Contents: Read and write`
+4. Copy the token
+5. In your repository: **Settings → Secrets and variables → Actions**
+6. Click **New repository secret**
+7. Name: `AGILEFLOW_TOKEN`, value: your token
+
+AgileFlow checks `AGILEFLOW_TOKEN` first, then falls back to `GITHUB_TOKEN`. When `AGILEFLOW_TOKEN` is set, no `permissions` block is needed.
+
+## Step 3: Create the release workflow
 
 `.github/workflows/release.yml`:
 
@@ -99,9 +103,9 @@ If no bump is needed (all commits are `chore`, `docs`, etc.), AgileFlow exits wi
 
 ## Troubleshooting
 
-**"AGILEFLOW_TOKEN not set"** — The secret is missing or not passed via `env:`. Verify the secret exists and the `env:` block is present in the step.
+**"No authentication token found"** — Neither `AGILEFLOW_TOKEN` nor `GITHUB_TOKEN` is available. If running in GitHub Actions, ensure the workflow has `permissions: contents: write`. If using a PAT, verify the `AGILEFLOW_TOKEN` secret exists.
 
-**"Resource not accessible by integration" / 403** — The token lacks `Contents: Read and write` permission. Regenerate with the correct scope.
+**"Resource not accessible by integration" / 403** — The token lacks `contents: write` permission. Add `permissions: contents: write` to your workflow, or regenerate your PAT with the correct scope.
 
 **"Bad credentials" / 401** — The token has expired or was revoked. Regenerate and update the secret.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logickernel/agileflow",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Automatic semantic versioning and changelog generation based on conventional commits",
   "main": "src/index.js",
   "bin": {

package/src/github-push.js

@@ -131,17 +131,20 @@ function makeRequest({ method, path, accessToken, body }) {
  * @returns {Promise<void>}
  */
 async function pushTag(tagName, message, remote = 'origin') {
-  const accessToken = process.env.AGILEFLOW_TOKEN;
+  const accessToken = process.env.AGILEFLOW_TOKEN || process.env.GITHUB_TOKEN;
   const repository = process.env.GITHUB_REPOSITORY;
   const commitSha = process.env.GITHUB_SHA;
-  
+
   if (!accessToken) {
     throw new Error(
-      `AGILEFLOW_TOKEN environment variable is required but not set.\n\n` +
-      `To fix this:\n` +
-      `1. Create a Personal Access Token with "contents: write" permission\n` +
-      `2. Add it as a repository secret named AGILEFLOW_TOKEN\n` +
-      `3. In your workflow, add: env: AGILEFLOW_TOKEN: \${{ secrets.AGILEFLOW_TOKEN }}`
+      `No authentication token found.\n\n` +
+      `AgileFlow looks for AGILEFLOW_TOKEN or GITHUB_TOKEN (in that order).\n\n` +
+      `In GitHub Actions, GITHUB_TOKEN is available automatically — just add\n` +
+      `permissions to your workflow:\n` +
+      `  permissions:\n` +
+      `    contents: write\n\n` +
+      `Or use a Personal Access Token with "contents: write" permission\n` +
+      `and store it as a secret named AGILEFLOW_TOKEN.`
     );
   }