feat: add workflow permission checks and update pull request body for skipped workflow edits

Author: CasperKristiansson

CHANGELOG.md

@@ -8,6 +8,16 @@ The project follows [Semantic Versioning](https://semver.org/) and adheres to th
 
 - Nothing yet.
 
+## [1.6.0] - 2025-10-10
+
+### Added
+
+- Include a workflow warning in generated pull request bodies when `.github/workflows/**` files change.
+
+### Fixed
+
+- Skip runs that would edit `.github/workflows/**` unless the provided token is a personal access token with the `workflow` scope, preventing GitHub App permission errors.
+
 ## [1.5.0] - 2025-10-10
 
 ### Fixed

README.md

@@ -217,11 +217,13 @@ This workflow requires:
 permissions:
   contents: write
   pull-requests: write
+```
 
 In addition to per-job permissions, the repository (or organization) wide setting under **Settings → Actions → General → Workflow permissions** must grant **Read and write permissions** and enable **“Allow GitHub Actions to create and approve pull requests”**. If that toggle cannot be enabled, provide a classic personal access token with `repo` scope via a secret (for example `PATCH_PR_TOKEN`) and export it as `GITHUB_TOKEN` when running the action.
 
 Commits authored by the action default to the current `GITHUB_ACTOR` (falling back to `github-actions[bot]`). Override this by setting `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL` (and matching `GIT_COMMITTER_*`) in the workflow environment before invoking the action if you need a custom identity.
-```
+
+> **Note:** The default `GITHUB_TOKEN` cannot push updates to `.github/workflows/**`. If the action needs to rewrite workflow files, supply a personal access token that includes the `workflow` scope (often via a secret mapped to `GITHUB_TOKEN`). Runs without that scope will skip applying workflow changes and exit with `workflow_permission_required`.
 
 ## FAQ
 
@@ -253,3 +255,7 @@ MIT. See `LICENSE`.
 > Like this Action? Star the repo. Adopt it in your org. Share feedback via issues or PRs.
 
 GitHub Action for zero-maintenance CPython patch updates across your repo.
+
+```
+
+```

dist/index.js

@@ -80208,6 +80208,16 @@ function groupMatchesByFile(matches) {
     }
     return grouped;
 }
+function isPersonalAccessToken(token) {
+    if (!token) {
+        return false;
+    }
+    const lowered = token.toLowerCase();
+    return (lowered.startsWith('ghp_') ||
+        lowered.startsWith('github_pat_') ||
+        lowered.startsWith('gho_') ||
+        lowered.startsWith('pat_'));
+}
 async function applyVersionUpdates(workspace, groupedMatches, newVersion) {
     for (const [relativePath, fileMatches] of groupedMatches) {
         const absolutePath = node_path_1.default.join(workspace, relativePath);
@@ -80371,7 +80381,7 @@ async function executeAction(options, dependencies) {
             filesChanged: uniqueFiles(scanResult.matches),
         };
     }
-    const matchesNeedingUpdate = scanResult.matches.filter((match) => match.matched !== latestVersion);
+    let matchesNeedingUpdate = scanResult.matches.filter((match) => match.matched !== latestVersion);
     if (matchesNeedingUpdate.length === 0) {
         return {
             status: 'skip',
@@ -80380,6 +80390,22 @@ async function executeAction(options, dependencies) {
             filesChanged: [],
         };
     }
+    const hasPersonalAccessToken = isPersonalAccessToken(githubToken);
+    const workflowMatches = matchesNeedingUpdate.filter((match) => match.file.startsWith('.github/workflows/'));
+    let skippedWorkflowFiles = [];
+    if (!hasPersonalAccessToken && workflowMatches.length > 0) {
+        skippedWorkflowFiles = uniqueFiles(workflowMatches);
+        matchesNeedingUpdate = matchesNeedingUpdate.filter((match) => !match.file.startsWith('.github/workflows/'));
+        if (matchesNeedingUpdate.length === 0) {
+            return {
+                status: 'skip',
+                reason: 'workflow_permission_required',
+                newVersion: latestVersion,
+                filesChanged: [],
+                details: { files: skippedWorkflowFiles },
+            };
+        }
+    }
     const filesChanged = uniqueFiles(matchesNeedingUpdate);
     const groupedMatches = groupMatchesByFile(matchesNeedingUpdate);
     if (dryRun || !allowPrCreation) {
@@ -80388,6 +80414,7 @@ async function executeAction(options, dependencies) {
             newVersion: latestVersion,
             filesChanged,
             dryRun: true,
+            workflowFilesSkipped: skippedWorkflowFiles.length > 0 ? skippedWorkflowFiles : undefined,
         };
     }
     if (!dependencies.createBranchAndCommit || !dependencies.pushBranch) {
@@ -80396,6 +80423,7 @@ async function executeAction(options, dependencies) {
             newVersion: latestVersion,
             filesChanged,
             dryRun: false,
+            workflowFilesSkipped: skippedWorkflowFiles.length > 0 ? skippedWorkflowFiles : undefined,
         };
     }
     if (!githubToken || !repository) {
@@ -80404,6 +80432,7 @@ async function executeAction(options, dependencies) {
             newVersion: latestVersion,
             filesChanged,
             dryRun: false,
+            workflowFilesSkipped: skippedWorkflowFiles.length > 0 ? skippedWorkflowFiles : undefined,
         };
     }
     const branchName = `chore/bump-python-${track}`;
@@ -80449,6 +80478,7 @@ async function executeAction(options, dependencies) {
                 newVersion: latestVersion,
                 filesChanged,
                 dryRun: false,
+                workflowFilesSkipped: skippedWorkflowFiles.length > 0 ? skippedWorkflowFiles : undefined,
             };
         }
         await dependencies.pushBranch({
@@ -80461,6 +80491,7 @@ async function executeAction(options, dependencies) {
             filesChanged,
             branchName: commitResult.branch,
             defaultBranch,
+            skippedWorkflowFiles,
         });
         const pullRequest = await dependencies.createOrUpdatePullRequest({
             owner: repository.owner,
@@ -80477,6 +80508,7 @@ async function executeAction(options, dependencies) {
             filesChanged,
             dryRun: false,
             pullRequest,
+            workflowFilesSkipped: skippedWorkflowFiles.length > 0 ? skippedWorkflowFiles : undefined,
         };
     }
     catch (error) {
@@ -80980,6 +81012,13 @@ function logSkip(result) {
             core.info(`Release notes do not contain the configured security keywords (${configuredKeywords}); skipping.`);
             break;
         }
+        case 'workflow_permission_required': {
+            const workflows = Array.isArray(result.details?.files)
+                ? (result.details?.files).join(', ')
+                : '.github/workflows';
+            core.warning(`This run detected workflow changes (${workflows}) but the provided token lacks workflow write permissions. Provide a personal access token with the "workflow" scope and set it as GITHUB_TOKEN to apply these updates.`);
+            break;
+        }
         default:
             core.info(`Skipping with reason ${result.reason}.`);
             break;
@@ -81016,6 +81055,9 @@ function summarizeResult(result) {
             const { action, number, url } = result.pullRequest;
             core.info(`Pull request ${action}: #${number}${url ? ` (${url})` : ''}`);
         }
+        if (result.workflowFilesSkipped && result.workflowFilesSkipped.length > 0) {
+            core.warning(`Skipped updating workflow files due to missing workflow permissions: ${result.workflowFilesSkipped.join(', ')}`);
+        }
     }
     else {
         logSkip(result);
@@ -81163,11 +81205,11 @@ if (require.main === require.cache[eval('__filename')]) {
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.generatePullRequestBody = generatePullRequestBody;
 function generatePullRequestBody(options) {
-    const { track, newVersion, filesChanged, branchName, defaultBranch } = options;
+    const { track, newVersion, filesChanged, branchName, defaultBranch, skippedWorkflowFiles } = options;
     const filesSection = filesChanged.length
         ? filesChanged.map((file) => `- \`${file}\``).join('\n')
         : 'No files were modified in this bump.';
-    return [
+    const bodySections = [
         '## Summary',
         '',
         `- Bump CPython ${track} pins to \`${newVersion}\`.`,
@@ -81176,25 +81218,12 @@ function generatePullRequestBody(options) {
         '',
         filesSection,
         '',
-        '## Rollback',
-        '',
-        'Before merge, close this PR and delete the branch:',
-        '',
-        '```sh',
-        `git push origin --delete ${branchName}`,
-        '```',
-        '',
-        `After merge, revert the change on ${defaultBranch}:`,
-        '',
-        '```sh',
-        `git checkout ${defaultBranch}`,
-        `git pull --ff-only origin ${defaultBranch}`,
-        'git revert --no-edit <merge_commit_sha>',
-        `git push origin ${defaultBranch}`,
-        '```',
-        '',
-        'Replace `<merge_commit_sha>` with the SHA of the merge commit if rollback is required.',
-    ].join('\n');
+    ];
+    if (skippedWorkflowFiles && skippedWorkflowFiles.length > 0) {
+        bodySections.push('## ⚠️ Workflow File Notice', '', 'The following workflow files were detected but left unchanged because the provided token lacks the `workflow` scope:', '', ...skippedWorkflowFiles.map((file) => `- \`${file}\``), '', 'Provide a personal access token with the `workflow` scope (for example via `GITHUB_TOKEN`) before rerunning to update these files automatically.', '');
+    }
+    bodySections.push('## Rollback', '', 'Before merge, close this PR and delete the branch:', '', '```sh', `git push origin --delete ${branchName}`, '```', '', `After merge, revert the change on ${defaultBranch}:`, '', '```sh', `git checkout ${defaultBranch}`, `git pull --ff-only origin ${defaultBranch}`, 'git revert --no-edit <merge_commit_sha>', `git push origin ${defaultBranch}`, '```', '', 'Replace `<merge_commit_sha>` with the SHA of the merge commit if rollback is required.');
+    return bodySections.join('\n');
 }
 
 

src/action-execution.ts

@@ -33,7 +33,8 @@ export type SkipReason =
   | 'pr_exists'
   | 'pr_creation_failed'
   | 'pre_release_guarded'
-  | 'security_gate_blocked';
+  | 'security_gate_blocked'
+  | 'workflow_permission_required';
 
 export interface ExecuteOptions {
   workspace: string;
@@ -84,6 +85,7 @@ export interface SuccessResult {
   filesChanged: string[];
   dryRun: boolean;
   pullRequest?: PullRequestResult;
+  workflowFilesSkipped?: string[];
 }
 
 export type ExecuteResult = SkipResult | SuccessResult;
@@ -109,6 +111,20 @@ function groupMatchesByFile(matches: VersionMatch[]): Map<string, VersionMatch[]
   return grouped;
 }
 
+function isPersonalAccessToken(token: string | undefined): boolean {
+  if (!token) {
+    return false;
+  }
+
+  const lowered = token.toLowerCase();
+  return (
+    lowered.startsWith('ghp_') ||
+    lowered.startsWith('github_pat_') ||
+    lowered.startsWith('gho_') ||
+    lowered.startsWith('pat_')
+  );
+}
+
 async function applyVersionUpdates(
   workspace: string,
   groupedMatches: Map<string, VersionMatch[]>,
@@ -334,9 +350,7 @@ export async function executeAction(
     } satisfies SkipResult;
   }
 
-  const matchesNeedingUpdate = scanResult.matches.filter(
-    (match) => match.matched !== latestVersion,
-  );
+  let matchesNeedingUpdate = scanResult.matches.filter((match) => match.matched !== latestVersion);
 
   if (matchesNeedingUpdate.length === 0) {
     return {
@@ -347,6 +361,30 @@ export async function executeAction(
     } satisfies SkipResult;
   }
 
+  const hasPersonalAccessToken = isPersonalAccessToken(githubToken);
+  const workflowMatches = matchesNeedingUpdate.filter((match) =>
+    match.file.startsWith('.github/workflows/'),
+  );
+
+  let skippedWorkflowFiles: string[] = [];
+
+  if (!hasPersonalAccessToken && workflowMatches.length > 0) {
+    skippedWorkflowFiles = uniqueFiles(workflowMatches);
+    matchesNeedingUpdate = matchesNeedingUpdate.filter(
+      (match) => !match.file.startsWith('.github/workflows/'),
+    );
+
+    if (matchesNeedingUpdate.length === 0) {
+      return {
+        status: 'skip',
+        reason: 'workflow_permission_required',
+        newVersion: latestVersion,
+        filesChanged: [],
+        details: { files: skippedWorkflowFiles },
+      } satisfies SkipResult;
+    }
+  }
+
   const filesChanged = uniqueFiles(matchesNeedingUpdate);
   const groupedMatches = groupMatchesByFile(matchesNeedingUpdate);
 
@@ -356,6 +394,7 @@ export async function executeAction(
       newVersion: latestVersion,
       filesChanged,
       dryRun: true,
+      workflowFilesSkipped: skippedWorkflowFiles.length > 0 ? skippedWorkflowFiles : undefined,
     } satisfies SuccessResult;
   }
 
@@ -365,6 +404,7 @@ export async function executeAction(
       newVersion: latestVersion,
       filesChanged,
       dryRun: false,
+      workflowFilesSkipped: skippedWorkflowFiles.length > 0 ? skippedWorkflowFiles : undefined,
     } satisfies SuccessResult;
   }
 
@@ -374,6 +414,7 @@ export async function executeAction(
       newVersion: latestVersion,
       filesChanged,
       dryRun: false,
+      workflowFilesSkipped: skippedWorkflowFiles.length > 0 ? skippedWorkflowFiles : undefined,
     } satisfies SuccessResult;
   }
 
@@ -427,6 +468,7 @@ export async function executeAction(
         newVersion: latestVersion,
         filesChanged,
         dryRun: false,
+        workflowFilesSkipped: skippedWorkflowFiles.length > 0 ? skippedWorkflowFiles : undefined,
       } satisfies SuccessResult;
     }
 
@@ -441,6 +483,7 @@ export async function executeAction(
       filesChanged,
       branchName: commitResult.branch,
       defaultBranch,
+      skippedWorkflowFiles,
     });
 
     const pullRequest = await dependencies.createOrUpdatePullRequest({
@@ -459,6 +502,7 @@ export async function executeAction(
       filesChanged,
       dryRun: false,
       pullRequest,
+      workflowFilesSkipped: skippedWorkflowFiles.length > 0 ? skippedWorkflowFiles : undefined,
     } satisfies SuccessResult;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

src/index.ts

@@ -173,6 +173,15 @@ function logSkip(result: SkipResult): void {
       );
       break;
     }
+    case 'workflow_permission_required': {
+      const workflows = Array.isArray(result.details?.files)
+        ? (result.details?.files as string[]).join(', ')
+        : '.github/workflows';
+      core.warning(
+        `This run detected workflow changes (${workflows}) but the provided token lacks workflow write permissions. Provide a personal access token with the "workflow" scope and set it as GITHUB_TOKEN to apply these updates.`,
+      );
+      break;
+    }
     default:
       core.info(`Skipping with reason ${result.reason}.`);
       break;
@@ -214,6 +223,11 @@ function summarizeResult(result: ExecuteResult): void {
       const { action, number, url } = result.pullRequest;
       core.info(`Pull request ${action}: #${number}${url ? ` (${url})` : ''}`);
     }
+    if (result.workflowFilesSkipped && result.workflowFilesSkipped.length > 0) {
+      core.warning(
+        `Skipped updating workflow files due to missing workflow permissions: ${result.workflowFilesSkipped.join(', ')}`,
+      );
+    }
   } else {
     logSkip(result);
   }