feat: implement offline mode with snapshot support for network access

Author: CasperKristiansson

README.md

@@ -147,6 +147,18 @@ the context of a real repository:
 Each template ships with a README snippet and status badge you can adapt when
 bootstrapping your own public showcase repository.
 
+### Offline mode
+
+Set `NO_NETWORK_FALLBACK=true` and supply snapshots so the action can run without hitting
+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`.
+
+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.
+
 ---
 
 ## Permissions

SECURITY.md

@@ -30,8 +30,10 @@ External network access is limited to:
 - `www.python.org` – fallback source to confirm released patch versions.
 
 No telemetry or analytics endpoints are used. If you need to run the action in a
-restricted environment, consider mirroring the above endpoints and pointing the
-workflow to your mirrors.
+restricted environment, you can enable offline mode by setting `NO_NETWORK_FALLBACK=true`
+and providing snapshot data via `CPYTHON_TAGS_SNAPSHOT`, `PYTHON_ORG_HTML_SNAPSHOT`, and
+`RUNNER_MANIFEST_SNAPSHOT`. Each variable accepts either inline JSON/HTML or a path to a
+local file containing the snapshot data.
 
 ## Handling secrets
 

docs/tasks.md

@@ -241,7 +241,7 @@ Use Context7 MCP for up to date documentation.
         PR body includes exact git commands.
         Verify: Snapshot contains commands with placeholders.
 
-40. [ ] **No extra telemetry**
+40. [x] **No extra telemetry**
         Only GitHub + python.org calls. Env `NO_NETWORK_FALLBACK=true` supported with injected data.
         Verify: Network-blocked tests pass using fixtures.
 

src/action-execution.ts

@@ -13,6 +13,7 @@ import {
 } from './versioning';
 import { createOrUpdatePullRequest, findExistingPullRequest, type PullRequestResult } from './git';
 import { generatePullRequestBody } from './pr-body';
+import type { StableTag } from './github';
 
 export type SkipReason =
   | 'no_matches_found'
@@ -34,6 +35,12 @@ export interface ExecuteOptions {
   repository?: { owner: string; repo: string } | null;
   defaultBranch?: string;
   allowPrCreation?: boolean;
+  noNetworkFallback?: boolean;
+  snapshots?: {
+    cpythonTags?: StableTag[];
+    pythonOrgHtml?: string;
+    runnerManifest?: unknown;
+  };
 }
 
 export interface ExecuteDependencies {
@@ -114,6 +121,8 @@ export async function executeAction(
     repository,
     defaultBranch = 'main',
     allowPrCreation = false,
+    noNetworkFallback = false,
+    snapshots,
   } = options;
 
   const scanResult = await dependencies.scanForPythonVersions({
@@ -143,8 +152,14 @@ export async function executeAction(
   const latestPatch = await dependencies.resolveLatestPatch(track, {
     includePrerelease,
     token: githubToken,
+    tags: snapshots?.cpythonTags,
+    noNetworkFallback,
+  });
+  const fallback = await dependencies.fetchLatestFromPythonOrg({
+    track,
+    htmlSnapshot: snapshots?.pythonOrgHtml,
+    noNetworkFallback,
   });
-  const fallback = await dependencies.fetchLatestFromPythonOrg({ track });
   const latestVersion = selectLatestVersion(track, latestPatch, fallback);
 
   const guard = dependencies.enforcePreReleaseGuard(includePrerelease, latestVersion);
@@ -156,7 +171,10 @@ export async function executeAction(
     } satisfies SkipResult;
   }
 
-  const availability = await dependencies.fetchRunnerAvailability(latestVersion);
+  const availability = await dependencies.fetchRunnerAvailability(latestVersion, {
+    manifestSnapshot: snapshots?.runnerManifest,
+    noNetworkFallback,
+  });
   const missingRunners = determineMissingRunners(availability);
   if (missingRunners.length > 0) {
     return {

src/index.ts

@@ -1,3 +1,4 @@
+import { existsSync, readFileSync } from 'node:fs';
 import process from 'node:process';
 
 import * as core from '@actions/core';
@@ -17,6 +18,7 @@ import {
 } from './versioning';
 import { createOrUpdatePullRequest, findExistingPullRequest } from './git';
 import { validateTrack } from './config';
+import type { StableTag } from './github';
 
 const DEFAULT_TRACK = '3.13';
 const DEFAULT_PATHS = [
@@ -51,6 +53,48 @@ function resolvePathsInput(): string[] {
   return explicitPaths.length > 0 ? explicitPaths : DEFAULT_PATHS;
 }
 
+function loadJsonSnapshot(envName: string): unknown | undefined {
+  const raw = process.env[envName];
+  if (!raw || raw.trim() === '') {
+    return undefined;
+  }
+
+  const trimmed = raw.trim();
+
+  try {
+    return JSON.parse(trimmed);
+  } catch (primaryError) {
+    if (existsSync(trimmed)) {
+      try {
+        const fileContent = readFileSync(trimmed, 'utf8');
+        return JSON.parse(fileContent);
+      } catch (fileError) {
+        throw new Error(
+          `Failed to parse JSON snapshot from ${envName}. Ensure it contains valid JSON or a path to a JSON file. Original error: ${(fileError as Error).message}`,
+        );
+      }
+    }
+
+    throw new Error(
+      `Failed to parse JSON snapshot from ${envName}. Provide valid JSON or a path to a JSON file. Original error: ${(primaryError as Error).message}`,
+    );
+  }
+}
+
+function loadTextSnapshot(envName: string): string | undefined {
+  const raw = process.env[envName];
+  if (!raw || raw.trim() === '') {
+    return undefined;
+  }
+
+  const trimmed = raw.trim();
+  if (existsSync(trimmed)) {
+    return readFileSync(trimmed, 'utf8');
+  }
+
+  return raw;
+}
+
 function parseRepository(slug: string | undefined): { owner: string; repo: string } | null {
   if (!slug) {
     return null;
@@ -165,6 +209,31 @@ export async function run(): Promise<void> {
     const repository = parseRepository(process.env.GITHUB_REPOSITORY);
     const githubToken = process.env.GITHUB_TOKEN;
     const defaultBranch = process.env.GITHUB_BASE_REF ?? process.env.GITHUB_REF_NAME ?? 'main';
+    const noNetworkFallback = (process.env.NO_NETWORK_FALLBACK ?? '').toLowerCase() === 'true';
+
+    let cpythonTagsSnapshot: StableTag[] | undefined;
+    let pythonOrgHtmlSnapshot: string | undefined;
+    let runnerManifestSnapshot: unknown | undefined;
+
+    try {
+      const rawTagsSnapshot = loadJsonSnapshot('CPYTHON_TAGS_SNAPSHOT');
+      if (rawTagsSnapshot !== undefined) {
+        if (!Array.isArray(rawTagsSnapshot)) {
+          throw new Error('CPYTHON_TAGS_SNAPSHOT must be a JSON array.');
+        }
+        cpythonTagsSnapshot = rawTagsSnapshot as StableTag[];
+      }
+
+      pythonOrgHtmlSnapshot = loadTextSnapshot('PYTHON_ORG_HTML_SNAPSHOT');
+      runnerManifestSnapshot = loadJsonSnapshot('RUNNER_MANIFEST_SNAPSHOT');
+    } catch (snapshotError) {
+      if (snapshotError instanceof Error) {
+        core.setFailed(snapshotError.message);
+      } else {
+        core.setFailed('Failed to load offline snapshots.');
+      }
+      return;
+    }
 
     core.startGroup('Configuration');
     core.info(`workspace: ${workspace}`);
@@ -173,6 +242,7 @@ export async function run(): Promise<void> {
     core.info(`paths (${effectivePaths.length}): ${effectivePaths.join(', ')}`);
     core.info(`automerge: ${automerge}`);
     core.info(`dry_run: ${dryRun}`);
+    core.info(`no_network_fallback: ${noNetworkFallback}`);
     if (repository) {
       core.info(`repository: ${repository.owner}/${repository.repo}`);
     }
@@ -196,6 +266,12 @@ export async function run(): Promise<void> {
         repository,
         defaultBranch,
         allowPrCreation: false,
+        noNetworkFallback,
+        snapshots: {
+          cpythonTags: cpythonTagsSnapshot,
+          pythonOrgHtml: pythonOrgHtmlSnapshot,
+          runnerManifest: runnerManifestSnapshot,
+        },
       },
       dependencies,
     );

src/versioning/latest-patch-resolver.ts

@@ -8,6 +8,8 @@ export interface ResolveLatestPatchOptions extends FetchStableTagsOptions {
   includePrerelease?: boolean;
   /// Optional override for the tag list, used primarily for testing.
   tags?: StableTag[];
+  /// When true, skip network calls and require tags override.
+  noNetworkFallback?: boolean;
 }
 
 export interface LatestPatchResult {
@@ -43,7 +45,13 @@ export async function resolveLatestPatch(
     throw new Error(`Track "${track}" must be in the form X.Y`);
   }
 
-  const { includePrerelease = false, tags, ...fetchOptions } = options;
+  const { includePrerelease = false, tags, noNetworkFallback = false, ...fetchOptions } = options;
+
+  if (!tags && noNetworkFallback) {
+    throw new Error(
+      'Network access disabled via NO_NETWORK_FALLBACK. Provide tags override to resolve latest patch.',
+    );
+  }
 
   const stableTags = tags ?? (await fetchStableCpythonTags(fetchOptions));
   const candidates = filterByTrack(stableTags, normalizedTrack, includePrerelease);

src/versioning/python-org-fallback.ts

@@ -9,6 +9,8 @@ type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 export interface PythonOrgFallbackOptions {
   fetchImpl?: FetchLike;
   track: string;
+  noNetworkFallback?: boolean;
+  htmlSnapshot?: string;
 }
 
 export interface PythonOrgVersion {
@@ -36,22 +38,35 @@ function extractVersions(html: string): string[] {
 export async function fetchLatestFromPythonOrg(
   options: PythonOrgFallbackOptions,
 ): Promise<PythonOrgVersion | null> {
-  const { track, fetchImpl = defaultFetch } = options;
+  const { track, fetchImpl = defaultFetch, noNetworkFallback = false, htmlSnapshot } = options;
   const normalizedTrack = track.trim();
   if (!/^\d+\.\d+$/.test(normalizedTrack)) {
     throw new Error(`Track "${track}" must be in the form X.Y`);
   }
 
-  const response = await fetchImpl(PYTHON_RELEASES_URL, {
-    method: 'GET',
-  } satisfies RequestInit);
+  let htmlContent: string;
 
-  if (!response.ok) {
-    throw new Error(`Failed to fetch python.org releases (status ${response.status}).`);
+  if (htmlSnapshot) {
+    htmlContent = htmlSnapshot;
+  } else {
+    if (noNetworkFallback) {
+      throw new Error(
+        'Network access disabled via NO_NETWORK_FALLBACK. Provide htmlSnapshot to fetchLatestFromPythonOrg.',
+      );
+    }
+
+    const response = await fetchImpl(PYTHON_RELEASES_URL, {
+      method: 'GET',
+    } satisfies RequestInit);
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch python.org releases (status ${response.status}).`);
+    }
+
+    htmlContent = await response.text();
   }
 
-  const html = await response.text();
-  const versions = extractVersions(html);
+  const versions = extractVersions(htmlContent);
 
   const candidates = versions.filter((version) => version.startsWith(`${normalizedTrack}.`));
   if (candidates.length === 0) {

src/versioning/runner-availability.ts

@@ -9,6 +9,8 @@ type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 export interface RunnerAvailabilityOptions {
   fetchImpl?: FetchLike;
   signal?: AbortSignal;
+  noNetworkFallback?: boolean;
+  manifestSnapshot?: unknown;
 }
 
 export interface RunnerAvailability {
@@ -69,20 +71,33 @@ export async function fetchRunnerAvailability(
   version: string,
   options: RunnerAvailabilityOptions = {},
 ): Promise<RunnerAvailability | null> {
-  const { fetchImpl = defaultFetch, signal } = options;
+  const { fetchImpl = defaultFetch, signal, noNetworkFallback = false, manifestSnapshot } = options;
 
-  const response = await fetchImpl(MANIFEST_URL, {
-    method: 'GET',
-    signal,
-  } satisfies RequestInit);
+  let payload: unknown;
 
-  if (!response.ok) {
-    throw new Error(
-      `Failed to fetch versions manifest from actions/python-versions (status ${response.status}).`,
-    );
+  if (manifestSnapshot !== undefined) {
+    payload = manifestSnapshot;
+  } else {
+    if (noNetworkFallback) {
+      throw new Error(
+        'Network access disabled via NO_NETWORK_FALLBACK. Provide manifestSnapshot to fetchRunnerAvailability.',
+      );
+    }
+
+    const response = await fetchImpl(MANIFEST_URL, {
+      method: 'GET',
+      signal,
+    } satisfies RequestInit);
+
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch versions manifest from actions/python-versions (status ${response.status}).`,
+      );
+    }
+
+    payload = await response.json();
   }
 
-  const payload = await response.json();
   const manifestResult = manifestSchema.safeParse(payload);
 
   if (!manifestResult.success) {

tests/action-execution.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it, beforeEach, vi } from 'vitest';
-
-import { executeAction, type ExecuteDependencies } from '../src/action-execution';
+import {
+  executeAction,
+  type ExecuteDependencies,
+  type ExecuteOptions,
+} from '../src/action-execution';
+import type { PullRequestResult } from '../src/git';
 import type { VersionMatch } from '../src/scanning';
 import type { ScanResult } from '../src/scanning/scanner';
 
@@ -38,14 +42,16 @@ const baseDependencies = (): ExecuteDependencies => ({
     availableOn: { linux: true, mac: true, win: true },
   })),
   findExistingPullRequest: vi.fn(),
-  createOrUpdatePullRequest: vi.fn(async () => ({
-    action: 'created',
-    number: 1,
-    url: undefined,
-  })),
+  createOrUpdatePullRequest: vi.fn(
+    async (): Promise<PullRequestResult> => ({
+      action: 'created',
+      number: 1,
+      url: undefined,
+    }),
+  ),
 });
 
-const baseOptions = {
+const baseOptions: ExecuteOptions = {
   workspace: '.',
   track: '3.13',
   includePrerelease: false,
@@ -56,7 +62,9 @@ const baseOptions = {
   repository: null,
   defaultBranch: 'main',
   allowPrCreation: false,
-} as const;
+  noNetworkFallback: false,
+  snapshots: undefined,
+};
 
 describe('executeAction failure modes', () => {
   let deps: ExecuteDependencies;
@@ -145,7 +153,7 @@ describe('executeAction failure modes', () => {
 
   it('returns pr_creation_failed when PR creation throws', async () => {
     deps.findExistingPullRequest = vi.fn(async () => null);
-    deps.createOrUpdatePullRequest = vi.fn(async () => {
+    deps.createOrUpdatePullRequest = vi.fn(async (): Promise<PullRequestResult> => {
       throw new Error('boom');
     });