feat: add security keyword gating and fetch release notes functionality

Author: CasperKristiansson

README.md

@@ -63,6 +63,7 @@ CPython Patch PR Action is a GitHub Action that automatically scans your reposit
 | `paths`                  | false    | _(see default globs)_ | Newline-separated glob patterns to scan.                                                |
 | `automerge`              | false    | `false`               | Label or merge the bump PR once checks pass.                                            |
 | `dry_run`                | false    | `false`               | Skip file writes and emit a change summary instead.                                     |
+| `security_keywords`      | false    | _(empty)_             | Require the release notes to contain at least one of the provided keywords before upgrading. |
 | `use_external_pr_action` | false    | `false`               | Emit outputs for `peter-evans/create-pull-request` instead of using Octokit internally. |
 
 **Default globs**
@@ -133,6 +134,33 @@ with:
 
 Set `automerge: true` and wire a follow-up job that applies your preferred automerge strategy (label-based, direct merge, etc.) based on the outputs emitted by the action.
 
+### Security keyword gate
+
+Supply `security_keywords` (one per line) to require matching terms inside the CPython release notes before applying an update. This is useful for only auto-rolling releases that contain security fixes:
+
+```yaml
+with:
+  security_keywords: |
+    CVE
+    security
+```
+
+When the keywords are provided, the action fetches the GitHub release notes for the resolved tag (or uses the optional `RELEASE_NOTES_SNAPSHOT` offline input) and skips the run unless at least one keyword is present.
+
+### Renovate/Dependabot coexistence
+
+If Renovate or Dependabot also try to bump CPython patch versions, they will race with this action
+and open competing pull requests. Use the sample configurations below to disable CPython patch bumps
+while still allowing those tools to manage other dependencies:
+
+- `examples/coexistence/renovate.json` disables patch updates for the `python` base image in Dockerfiles
+  and any custom regex managers that match CPython pins.
+- `examples/coexistence/dependabot.yml` ignores semver patch updates for the `python` Docker image
+  while keeping other ecosystems enabled.
+
+Both samples are validated by the test suite so you can copy them verbatim and adjust schedules or
+additional dependency rules as needed.
+
 ---
 
 ## Example consumer repositories
@@ -155,6 +183,7 @@ external endpoints:
 - `CPYTHON_TAGS_SNAPSHOT` – JSON array of CPython tag objects.
 - `PYTHON_ORG_HTML_SNAPSHOT` – Raw HTML or path to a saved python.org releases page.
 - `RUNNER_MANIFEST_SNAPSHOT` – JSON manifest compatible with `actions/python-versions`.
+- `RELEASE_NOTES_SNAPSHOT` – JSON object mapping tags or versions to release note strings.
 
 Each variable accepts either the data directly or a path to a file containing the snapshot. When
 offline mode is enabled and a snapshot is missing, the run will fail fast with a clear message.

action.yml

@@ -28,6 +28,10 @@ inputs:
     description: Skip file modifications and output the planned changes only.
     required: false
     default: 'false'
+  security_keywords:
+    description: Newline-separated keywords that must appear in the release notes before applying an update.
+    required: false
+    default: ''
 outputs:
   new_version:
     description: Resolved CPython patch version (for example 3.13.5).

docs/tasks.md

@@ -247,11 +247,11 @@ Use Context7 MCP for up to date documentation.
 
 ## 10) Optional compatibility and polish
 
-41. [ ] **Renovate/Dependabot coexistence docs**
+41. [x] **Renovate/Dependabot coexistence docs**
         Provide ignore rules to avoid flapping.
         Verify: Example configs tested.
 
-42. [ ] **Security keyword gating**
+42. [x] **Security keyword gating**
         Input `security_keywords` to gate bumps by release notes.
         Verify: Mock notes trigger gate.
 

examples/coexistence/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    ignore:
+      - dependency-name: "python"
+        update-types:
+          - "version-update:semver-patch"
+    # CPython patch bumps are managed by python-version-patch-pr
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

examples/coexistence/renovate.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended"],
+  "packageRules": [
+    {
+      "description": "Let python-version-patch-pr handle CPython patch bumps found in Dockerfiles and regex managers",
+      "matchManagers": ["dockerfile", "regex"],
+      "matchPackagePatterns": ["^python$"],
+      "matchUpdateTypes": ["patch"],
+      "enabled": false
+    }
+  ]
+}

package-lock.json

@@ -63,6 +63,7 @@
     "rimraf": "^6.0.1",
     "tsx": "^4.20.6",
     "typescript": "^5.4.5",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "yaml": "^2.8.1"
   }
 }

package.json

@@ -8,6 +8,7 @@ import {
   enforcePreReleaseGuard,
   fetchLatestFromPythonOrg,
   fetchRunnerAvailability,
+  fetchReleaseNotes,
   resolveLatestPatch,
   type LatestPatchResult,
 } from './versioning';
@@ -22,7 +23,8 @@ export type SkipReason =
   | 'already_latest'
   | 'pr_exists'
   | 'pr_creation_failed'
-  | 'pre_release_guarded';
+  | 'pre_release_guarded'
+  | 'security_gate_blocked';
 
 export interface ExecuteOptions {
   workspace: string;
@@ -36,10 +38,12 @@ export interface ExecuteOptions {
   defaultBranch?: string;
   allowPrCreation?: boolean;
   noNetworkFallback?: boolean;
+  securityKeywords?: string[];
   snapshots?: {
     cpythonTags?: StableTag[];
     pythonOrgHtml?: string;
     runnerManifest?: unknown;
+    releaseNotes?: Record<string, string>;
   };
 }
 
@@ -52,6 +56,7 @@ export interface ExecuteDependencies {
   fetchRunnerAvailability: typeof fetchRunnerAvailability;
   findExistingPullRequest?: typeof findExistingPullRequest;
   createOrUpdatePullRequest?: typeof createOrUpdatePullRequest;
+  fetchReleaseNotes?: typeof fetchReleaseNotes;
 }
 
 export interface SkipResult {
@@ -122,6 +127,7 @@ export async function executeAction(
     defaultBranch = 'main',
     allowPrCreation = false,
     noNetworkFallback = false,
+    securityKeywords = [],
     snapshots,
   } = options;
 
@@ -171,6 +177,73 @@ export async function executeAction(
     } satisfies SkipResult;
   }
 
+  const normalizedSecurityKeywords = securityKeywords
+    .map((keyword) => keyword.trim())
+    .filter((keyword) => keyword.length > 0);
+
+  if (normalizedSecurityKeywords.length > 0) {
+    const releaseNotesLookup = snapshots?.releaseNotes;
+    const releaseNotesFromSnapshot =
+      releaseNotesLookup &&
+      [latestPatch?.tagName, `v${latestVersion}`, latestVersion].reduce<string | undefined>(
+        (acc, key) => {
+          if (acc) {
+            return acc;
+          }
+          if (!key) {
+            return undefined;
+          }
+          const direct = releaseNotesLookup[key];
+          if (typeof direct === 'string') {
+            return direct;
+          }
+          return undefined;
+        },
+        undefined,
+      );
+
+    let releaseNotesText = releaseNotesFromSnapshot;
+    let releaseNotesFound = releaseNotesText != null;
+
+    if (!releaseNotesText && !noNetworkFallback && dependencies.fetchReleaseNotes) {
+      const tagForNotes = latestPatch?.tagName ?? `v${latestVersion}`;
+      releaseNotesText =
+        (await dependencies.fetchReleaseNotes(tagForNotes, {
+          token: githubToken,
+        })) ?? undefined;
+      releaseNotesFound = releaseNotesText != null;
+    }
+
+    if (releaseNotesText == null) {
+      return {
+        status: 'skip',
+        reason: 'security_gate_blocked',
+        newVersion: latestVersion,
+        details: {
+          keywords: normalizedSecurityKeywords,
+          releaseNotesFound,
+        },
+      } satisfies SkipResult;
+    }
+
+    const lowerCaseNotes = releaseNotesText.toLowerCase();
+    const matchedKeyword = normalizedSecurityKeywords.find((keyword) =>
+      lowerCaseNotes.includes(keyword.toLowerCase()),
+    );
+
+    if (!matchedKeyword) {
+      return {
+        status: 'skip',
+        reason: 'security_gate_blocked',
+        newVersion: latestVersion,
+        details: {
+          keywords: normalizedSecurityKeywords,
+          releaseNotesFound: true,
+        },
+      } satisfies SkipResult;
+    }
+  }
+
   const availability = await dependencies.fetchRunnerAvailability(latestVersion, {
     manifestSnapshot: snapshots?.runnerManifest,
     noNetworkFallback,

src/action-execution.ts

@@ -14,6 +14,7 @@ import {
   enforcePreReleaseGuard,
   fetchLatestFromPythonOrg,
   fetchRunnerAvailability,
+  fetchReleaseNotes,
   resolveLatestPatch,
 } from './versioning';
 import { createOrUpdatePullRequest, findExistingPullRequest } from './git';
@@ -53,6 +54,13 @@ function resolvePathsInput(): string[] {
   return explicitPaths.length > 0 ? explicitPaths : DEFAULT_PATHS;
 }
 
+function resolveSecurityKeywords(): string[] {
+  return core
+    .getMultilineInput('security_keywords', { trimWhitespace: true })
+    .map((keyword) => keyword.trim())
+    .filter((keyword) => keyword.length > 0);
+}
+
 function loadJsonSnapshot(envName: string): unknown | undefined {
   const raw = process.env[envName];
   if (!raw || raw.trim() === '') {
@@ -151,6 +159,15 @@ function logSkip(result: SkipResult): void {
     case 'pre_release_guarded':
       core.info('Latest tag is a pre-release and include_prerelease is false; skipping.');
       break;
+    case 'security_gate_blocked': {
+      const configuredKeywords = Array.isArray(result.details?.keywords)
+        ? (result.details?.keywords as string[]).join(', ')
+        : 'none';
+      core.info(
+        `Release notes do not contain the configured security keywords (${configuredKeywords}); skipping.`,
+      );
+      break;
+    }
     default:
       core.info(`Skipping with reason ${result.reason}.`);
       break;
@@ -167,6 +184,7 @@ function buildDependencies(): ExecuteDependencies {
     fetchRunnerAvailability,
     findExistingPullRequest,
     createOrUpdatePullRequest,
+    fetchReleaseNotes,
   };
 }
 
@@ -204,6 +222,7 @@ export async function run(): Promise<void> {
     const automerge = getBooleanInput('automerge', false);
     const dryRun = getBooleanInput('dry_run', false);
     const effectivePaths = resolvePathsInput();
+    const securityKeywords = resolveSecurityKeywords();
 
     const workspace = process.env.GITHUB_WORKSPACE ?? process.cwd();
     const repository = parseRepository(process.env.GITHUB_REPOSITORY);
@@ -214,6 +233,7 @@ export async function run(): Promise<void> {
     let cpythonTagsSnapshot: StableTag[] | undefined;
     let pythonOrgHtmlSnapshot: string | undefined;
     let runnerManifestSnapshot: unknown | undefined;
+    let releaseNotesSnapshot: Record<string, string> | undefined;
 
     try {
       const rawTagsSnapshot = loadJsonSnapshot('CPYTHON_TAGS_SNAPSHOT');
@@ -226,6 +246,22 @@ export async function run(): Promise<void> {
 
       pythonOrgHtmlSnapshot = loadTextSnapshot('PYTHON_ORG_HTML_SNAPSHOT');
       runnerManifestSnapshot = loadJsonSnapshot('RUNNER_MANIFEST_SNAPSHOT');
+
+      const rawReleaseNotesSnapshot = loadJsonSnapshot('RELEASE_NOTES_SNAPSHOT');
+      if (rawReleaseNotesSnapshot !== undefined) {
+        if (typeof rawReleaseNotesSnapshot !== 'object' || rawReleaseNotesSnapshot === null) {
+          throw new Error('RELEASE_NOTES_SNAPSHOT must be a JSON object mapping versions or tags to release note strings.');
+        }
+
+        const entries = Object.entries(rawReleaseNotesSnapshot as Record<string, unknown>);
+        for (const [, value] of entries) {
+          if (typeof value !== 'string') {
+            throw new Error('RELEASE_NOTES_SNAPSHOT values must be strings.');
+          }
+        }
+
+        releaseNotesSnapshot = Object.fromEntries(entries) as Record<string, string>;
+      }
     } catch (snapshotError) {
       if (snapshotError instanceof Error) {
         core.setFailed(snapshotError.message);
@@ -240,6 +276,9 @@ export async function run(): Promise<void> {
     core.info(`track: ${validatedTrack}`);
     core.info(`include_prerelease: ${includePrerelease}`);
     core.info(`paths (${effectivePaths.length}): ${effectivePaths.join(', ')}`);
+    core.info(
+      `security_keywords (${securityKeywords.length}): ${securityKeywords.length > 0 ? securityKeywords.join(', ') : '(none)'}`,
+    );
     core.info(`automerge: ${automerge}`);
     core.info(`dry_run: ${dryRun}`);
     core.info(`no_network_fallback: ${noNetworkFallback}`);
@@ -267,10 +306,12 @@ export async function run(): Promise<void> {
         defaultBranch,
         allowPrCreation: false,
         noNetworkFallback,
+        securityKeywords,
         snapshots: {
           cpythonTags: cpythonTagsSnapshot,
           pythonOrgHtml: pythonOrgHtmlSnapshot,
           runnerManifest: runnerManifestSnapshot,
+          releaseNotes: releaseNotesSnapshot,
         },
       },
       dependencies,

src/index.ts

@@ -9,3 +9,6 @@ export type { RunnerAvailability, RunnerAvailabilityOptions } from './runner-ava
 
 export { enforcePreReleaseGuard } from './pre-release-guard';
 export type { PreReleaseGuardResult } from './pre-release-guard';
+
+export { fetchReleaseNotes } from './release-notes';
+export type { FetchReleaseNotesOptions } from './release-notes';