ghcr-manager 0.9.4 → 0.9.6

package/CHANGELOG.md

@@ -7,6 +7,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.6] - 2026-05-21
+
+### Added
+
+- Cleanup audit now persists concrete selected tags in `cleanup_selected_tags`.
+- Cleanup schema docs now include a readable cleanup-decision view plus example SQL queries for audit inspection.
+- GHCR digest-tag helper relations are now modeled explicitly in scan data and manifest reachability.
+
+### Changed
+
+- Cleanup summary JSON now exposes derived affected manifests for fully deletable roots.
+- Cleanup Markdown now reads displayed counts from the summary arrays instead of carrying duplicate count fields.
+- Cleanup decision audit fields are now constrained more tightly in SQLite and TypeScript, including `selection_mode`,
+  `selection_reason`, and related block reason codes.
+- Digest-tag helper artifacts are now classified on `tags.is_digest_tag` and excluded from normal user-facing tag
+  selection and output.
+- Digest-tag helper terminology was simplified across code and SQL surfaces.
+- Schema docs now include a table of contents and collapsible example query blocks for easier GitHub browsing.
+
+### Fixed
+
+- Fixed remote action path handling for artifact upload and merge helper actions.
+- Cleanup reachability now follows digest-tag helper edges recursively, matching helper-artifact cascades more closely.
+
+## [0.9.5] - 2026-05-21
+
+### Changed
+
+- Renamed `upload-db-artifact` to `upload-artifacts`.
+- Raised cleanup summary defaults to 100 matched tags and 100 roots per section.
+
 ## [0.9.4] - 2026-05-21
 
 ### Changed

package/README.md

@@ -33,7 +33,7 @@ jobs:
 
       - name: Preview GHCR cleanup
         id: ghcr-manager
-        uses: gh-workflow/ghcr-manager@0.9.4
+        uses: gh-workflow/ghcr-manager@0.9.6
         with:
           command: cleanup
           token: ${{ github.token }}
@@ -44,7 +44,7 @@ jobs:
           keep-n-tagged: "10"
           exclude-tags: |
             latest
-          upload-db-artifact: true
+          upload-artifacts: true
 ```
 
 After the run:
@@ -72,7 +72,7 @@ The action supports three commands:
 ### Preview cleanup
 
 ```yaml
-- uses: gh-workflow/ghcr-manager@0.9.4
+- uses: gh-workflow/ghcr-manager@0.9.6
   with:
     command: cleanup
     token: ${{ github.token }}
@@ -87,13 +87,13 @@ The action supports three commands:
     exclude-tags: |
       latest
       stable
-    upload-db-artifact: true
+    upload-artifacts: true
 ```
 
 ### Apply cleanup
 
 ```yaml
-- uses: gh-workflow/ghcr-manager@0.9.4
+- uses: gh-workflow/ghcr-manager@0.9.6
   with:
     command: cleanup
     token: ${{ github.token }}
@@ -101,7 +101,7 @@ The action supports three commands:
     package: PACKAGE
     delete-untagged: true
     keep-n-tagged: "10"
-    upload-db-artifact: true
+    upload-artifacts: true
     scan-after-cleanup: true
 ```
 
@@ -112,7 +112,7 @@ Note: the second scan only runs if cleanup actually makes changes.
 ### Remove selected tags directly
 
 ```yaml
-- uses: gh-workflow/ghcr-manager@0.9.4
+- uses: gh-workflow/ghcr-manager@0.9.6
   with:
     command: untag
     token: ${{ github.token }}
@@ -128,7 +128,7 @@ Note: the second scan only runs if cleanup actually makes changes.
 ### Scan one package
 
 ```yaml
-- uses: gh-workflow/ghcr-manager@0.9.4
+- uses: gh-workflow/ghcr-manager@0.9.6
   with:
     command: scan
     token: ${{ github.token }}
@@ -149,7 +149,7 @@ Note: the second scan only runs if cleanup actually makes changes.
 | `owner`                      | Package owner                       | all  | Yes         |                                |
 | `package`                    | Package name                        | all  | Yes         |                                |
 | `db-path`                    | Local SQLite DB path                | s,c  | No          |                                |
-| `upload-db-artifact`         | Upload DB and summary artifact      | s,c  | No          | `false`                        |
+| `upload-artifacts`           | Upload DB and summary artifacts     | s,c  | No          | `false`                        |
 | `scan-after-cleanup`         | Run a second scan after cleanup     | c    | No          | `false`                        |
 | `db-artifact-retention-days` | Override artifact retention days    | s,c  | No          | `${{ github.retention_days }}` |
 | `delete-tags`                | Newline-separated tags to delete    | c,u  | for `untag` |                                |

package/dist/cleanup-summary/_cleanup-summary-markdown.js

@@ -1,5 +1,5 @@
-const _DEFAULT_MAX_DIRECT_TARGET_TAGS = 20;
-const _DEFAULT_MAX_ROOTS_PER_SECTION = 20;
+const _DEFAULT_MAX_DIRECT_TARGET_TAGS = 100;
+const _DEFAULT_MAX_ROOTS_PER_SECTION = 100;
 const _DEFAULT_MAX_TAGS_PER_ROOT = 4;
 export function renderCleanupSummaryMarkdown(summary, options) {
     const maxDirectTargetTags = options.maxDirectTargetTags ?? _DEFAULT_MAX_DIRECT_TARGET_TAGS;
@@ -12,10 +12,11 @@ export function renderCleanupSummaryMarkdown(summary, options) {
         "| --- | --- |",
         `| 📦 Package | \`${_escapeInlineCode(`${summary.owner}/${summary.packageName}`)}\` |`,
         `| ⚙️ Mode | ${summary.dryRun ? "Cleanup dry-run" : "Cleanup"} |`,
-        `| 🏷️ Matched tags | ${summary.validationSummary.directTargetTagCount} |`,
-        `| 🗑️ Fully deletable roots | ${summary.validationSummary.fullyDeletableRootCount} |`,
-        `| 🔗 Untag-only roots | ${summary.validationSummary.untagOnlyRootCount} |`,
-        `| 🛡️ Blocked roots | ${summary.validationSummary.blockedDeleteRootCount} |`,
+        `| 🏷️ Matched tags | ${summary.directTargetTags.length} |`,
+        `| 🗑️ Fully deletable roots | ${summary.fullyDeletableRoots.length} |`,
+        `| 🔗 Untag-only roots | ${summary.untagOnlyRoots.length} |`,
+        `| 🛡️ Blocked roots | ${summary.blockedRoots.length} |`,
+        `| 📄 Affected manifests | ${summary.affectedManifests.length} |`,
         ""
     ];
     lines.push(..._renderJsonDetails("⚙️ Cleanup filter", summary.plannerInputs));

package/dist/cleanup-summary/_cleanup-summary.d.ts

@@ -1,4 +1,4 @@
-import type { DeletePlan } from "../db/index.js";
+import type { DeletePlan, DeletePlanSelectionMode, DeletePlanSelectionReason } from "../db/index.js";
 import type { DeleteExecutionSummary } from "../execute/index.js";
 export interface CleanupSummaryRoot {
     versionId: number;
@@ -6,8 +6,8 @@ export interface CleanupSummaryRoot {
     manifestKind?: string;
     rootTags: string[];
     matchedTags: string[];
-    selectionMode: string;
-    selectionReason: string;
+    selectionMode: DeletePlanSelectionMode;
+    selectionReason: DeletePlanSelectionReason;
     validationStatus: "fully-deletable" | "blocked" | "untag-only";
     validationReasonCode: "untag-only-partial-tag-match" | "fully-deletable-no-retained-overlap" | "blocked-overlap-with-retained-root";
     validationReason: string;
@@ -16,6 +16,9 @@ export interface CleanupSummaryRoot {
     overlapDigest?: string;
     overlapManifestKind?: string;
 }
+export interface CleanupSummaryAffectedManifest {
+    digest: string;
+}
 export interface CleanupSummary {
     command: "cleanup";
     owner: string;
@@ -23,12 +26,12 @@ export interface CleanupSummary {
     scanCompletedAt: string;
     dryRun: boolean;
     plannerInputs: DeletePlan["plannerInputs"];
-    validationSummary: DeletePlan["validationSummary"];
     directTargetTags: string[];
     collateralTags: string[];
     fullyDeletableRoots: CleanupSummaryRoot[];
     untagOnlyRoots: CleanupSummaryRoot[];
     blockedRoots: CleanupSummaryRoot[];
+    affectedManifests: CleanupSummaryAffectedManifest[];
     deletedPackageVersions: DeleteExecutionSummary["deletedPackageVersions"];
     untaggedTags: DeleteExecutionSummary["untaggedTags"];
     unsupportedUntagRoots: DeleteExecutionSummary["unsupportedUntagRoots"];
@@ -36,5 +39,6 @@ export interface CleanupSummary {
 export declare function buildCleanupSummary(plan: DeletePlan, options: {
     dryRun: boolean;
     listRootTags: (versionId: number) => string[];
+    listAffectedManifestDigests: (rootDigests: string[]) => string[];
     executionSummary?: DeleteExecutionSummary;
 }): CleanupSummary;

package/dist/cleanup-summary/_cleanup-summary.js

@@ -1,6 +1,10 @@
 export function buildCleanupSummary(plan, options) {
     const directTargetTagSet = new Set(plan.directTargetTags);
     const roots = plan.rootDecisions.map((decision) => _mapRootDecision(decision, directTargetTagSet, options.listRootTags));
+    const fullyDeletableRoots = roots.filter((root) => root.validationStatus === "fully-deletable");
+    const blockedRoots = roots.filter((root) => root.validationStatus === "blocked");
+    const untagOnlyRoots = roots.filter((root) => root.validationStatus === "untag-only");
+    const affectedManifestDigests = options.listAffectedManifestDigests(fullyDeletableRoots.map((root) => root.digest));
     return {
         command: "cleanup",
         owner: plan.owner,
@@ -8,12 +12,12 @@ export function buildCleanupSummary(plan, options) {
         scanCompletedAt: plan.scanCompletedAt,
         dryRun: options.dryRun,
         plannerInputs: plan.plannerInputs,
-        validationSummary: plan.validationSummary,
         directTargetTags: plan.directTargetTags,
         collateralTags: plan.collateralTags,
-        fullyDeletableRoots: roots.filter((root) => root.validationStatus === "fully-deletable"),
-        untagOnlyRoots: roots.filter((root) => root.validationStatus === "untag-only"),
-        blockedRoots: roots.filter((root) => root.validationStatus === "blocked"),
+        fullyDeletableRoots,
+        untagOnlyRoots,
+        blockedRoots,
+        affectedManifests: affectedManifestDigests.map((digest) => ({ digest })),
         deletedPackageVersions: options.executionSummary?.deletedPackageVersions ?? [],
         untaggedTags: options.executionSummary?.untaggedTags ?? [],
         unsupportedUntagRoots: options.executionSummary?.unsupportedUntagRoots ?? []

package/dist/cleanup-summary/index.d.ts

@@ -1,2 +1,2 @@
-export { buildCleanupSummary, type CleanupSummary, type CleanupSummaryRoot } from "./_cleanup-summary.js";
+export { buildCleanupSummary, type CleanupSummary, type CleanupSummaryAffectedManifest, type CleanupSummaryRoot } from "./_cleanup-summary.js";
 export { renderCleanupSummaryMarkdown } from "./_cleanup-summary-markdown.js";

package/dist/cli/_cleanup-command.js

@@ -14,16 +14,18 @@ export async function handleCleanup(args) {
     try {
         const repository = new PlannerRepository(database, logger);
         const cleanupRunWriter = new CleanupRunWriter(database);
+        const scanId = repository.getLatestCompletedScanId(inputs.owner, inputs.packageName);
         logger.debug(`Starting cleanup for ${inputs.owner}/${inputs.packageName}`);
         const plan = loadDeletePlan(repository, resolveTagSelectors(database, inputs));
-        cleanupRunWriter.persistCleanupRun(repository.getLatestCompletedScanId(inputs.owner, inputs.packageName), plan, {
+        cleanupRunWriter.persistCleanupRun(scanId, plan, {
             dryRun,
             cleanupStartedAt: new Date().toISOString()
         });
         if (dryRun) {
             const summary = buildCleanupSummary(plan, {
                 dryRun: true,
-                listRootTags: (versionId) => _listRootTags(database, inputs.owner, inputs.packageName, versionId)
+                listRootTags: (versionId) => _listRootTags(database, inputs.owner, inputs.packageName, versionId),
+                listAffectedManifestDigests: (rootDigests) => _listAffectedManifestDigests(database, scanId, rootDigests)
             });
             logger.debug(`Completed dry-run cleanup for ${inputs.owner}/${inputs.packageName}`);
             console.log(JSON.stringify(summary));
@@ -37,6 +39,7 @@ export async function handleCleanup(args) {
         const summary = buildCleanupSummary(plan, {
             dryRun: false,
             listRootTags: (versionId) => _listRootTags(database, inputs.owner, inputs.packageName, versionId),
+            listAffectedManifestDigests: (rootDigests) => _listAffectedManifestDigests(database, scanId, rootDigests),
             executionSummary
         });
         logger.debug(`Completed cleanup for ${inputs.owner}/${inputs.packageName}`);
@@ -47,6 +50,22 @@ export async function handleCleanup(args) {
         database.close();
     }
 }
+function _listAffectedManifestDigests(database, scanId, rootDigests) {
+    if (rootDigests.length === 0) {
+        return [];
+    }
+    const placeholders = rootDigests.map(() => "?").join(", ");
+    const rows = database
+        .prepare(`
+        SELECT DISTINCT descendant_digest AS digest
+        FROM manifest_reachability
+        WHERE scan_id = ?
+          AND ancestor_digest IN (${placeholders})
+        ORDER BY descendant_digest
+      `)
+        .all(scanId, ...rootDigests);
+    return rows.map((row) => row.digest);
+}
 function _listRootTags(database, owner, packageName, versionId) {
     const rows = database
         .prepare(`
@@ -56,6 +75,7 @@ function _listRootTags(database, owner, packageName, versionId) {
         WHERE latest_scan.owner = ?
           AND latest_scan.package_name = ?
           AND tags.version_id = ?
+          AND tags.is_digest_tag = 0
         ORDER BY tags.tag
       `)
         .all(owner, packageName, versionId);

package/dist/cli/_tag-selector-resolver.js

@@ -77,7 +77,7 @@ function _listLatestBrokenIndexTags(database, owner, packageName, cutoffTimestam
     return rows.map((row) => row.tag);
 }
 // Some OCI tooling publishes companion artifacts such as signatures or attestations under
-// digest-derived tags in the same repository, for example `sha256-<digest>.sig`, while the
+// digest tags in the same repository, for example `sha256-<digest>.sig`, while the
 // actual relationship is the artifact's subject/referrer link to the parent digest.
 //
 // Public references:
@@ -94,7 +94,7 @@ function _listLatestOrphanedTags(database, owner, packageName, cutoffTimestamp)
     const rows = database
         .prepare(`
         SELECT DISTINCT dtr.tag
-        FROM v_digest_derived_tag_relations dtr
+        FROM v_digest_tag_relations dtr
         INNER JOIN package_versions pv
           ON pv.scan_id = dtr.scan_id
          AND pv.version_id = dtr.artifact_version_id

package/dist/core/_digest-tag.d.ts

@@ -0,0 +1,2 @@
+export declare function isDigestTag(tag: string): boolean;
+export declare function digestFromDigestTag(tag: string): string | null;

package/dist/core/_digest-tag.js

@@ -0,0 +1,12 @@
+export function isDigestTag(tag) {
+    return tag.startsWith("sha256-") && tag.length >= 71 && !_containsNonHex(tag.slice(7, 71));
+}
+export function digestFromDigestTag(tag) {
+    if (!isDigestTag(tag)) {
+        return null;
+    }
+    return `sha256:${tag.slice(7, 71)}`;
+}
+function _containsNonHex(value) {
+    return /[^0-9A-Fa-f]/.test(value);
+}

package/dist/core/_types.d.ts

@@ -1,4 +1,5 @@
 export type ManifestKind = "image_index" | "image_manifest" | "artifact_manifest" | "attestation_manifest" | "signature_manifest";
+export type ManifestEdgeKind = "image-child" | "referrer" | "digest-tag-referrer";
 export interface PackageVersionRecord {
     versionId: number;
     createdAt: string;
@@ -38,7 +39,7 @@ export interface ManifestDescriptorRecord {
 export interface ManifestEdgeRecord {
     parentDigest: string;
     childDigest: string;
-    edgeKind: "image-child" | "referrer";
+    edgeKind: ManifestEdgeKind;
 }
 export interface PackageSnapshot {
     packageName: string;

package/dist/core/index.d.ts

@@ -1,4 +1,5 @@
-export type { ManifestEdgeRecord, ManifestDescriptorRecord, ManifestKind, ManifestRecord, PackageSnapshot, PackageVersionRecord, TagRecord } from "./_types.js";
+export type { ManifestEdgeKind, ManifestEdgeRecord, ManifestDescriptorRecord, ManifestKind, ManifestRecord, PackageSnapshot, PackageVersionRecord, TagRecord } from "./_types.js";
 export type { HttpErrorResponse } from "./_http-error.js";
 export { buildHttpErrorMessage } from "./_http-error.js";
 export { getOwnerURIComponent } from "./_github-package-owner.js";
+export { digestFromDigestTag, isDigestTag } from "./_digest-tag.js";

package/dist/core/index.js

@@ -1,2 +1,3 @@
 export { buildHttpErrorMessage } from "./_http-error.js";
 export { getOwnerURIComponent } from "./_github-package-owner.js";
+export { digestFromDigestTag, isDigestTag } from "./_digest-tag.js";

package/dist/db/_cleanup-run-writer.js

@@ -2,72 +2,91 @@ import { randomUUID } from "node:crypto";
 import { resolveGitHubActionsRunUrl } from "./_github-actions-run-url.js";
 export class CleanupRunWriter {
     #database;
+    #insertSelectedTagStatement;
+    #insertRootDecisionStatement;
+    #insertProtectedRootBlockStatement;
+    #insertCleanupRunStatement;
     constructor(database) {
         this.#database = database;
+        this.#insertSelectedTagStatement = this.#database.prepare(`
+      INSERT INTO cleanup_selected_tags(
+        cleanup_run_id,
+        scan_id,
+        tag
+      )
+      VALUES(?, ?, ?)
+    `);
+        this.#insertRootDecisionStatement = this.#database.prepare(`
+      INSERT INTO cleanup_root_decisions(
+        cleanup_run_id,
+        scan_id,
+        digest,
+        selection_mode,
+        selection_reason,
+        validation_status,
+        validation_reason_code,
+        validation_reason,
+        blocking_digest,
+        overlap_digest
+      )
+      VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        this.#insertProtectedRootBlockStatement = this.#database.prepare(`
+      INSERT INTO cleanup_protected_root_blocks(
+        cleanup_run_id,
+        scan_id,
+        protected_digest,
+        blocked_digest,
+        block_reason_code,
+        overlap_digest
+      )
+      VALUES(?, ?, ?, ?, ?, ?)
+    `);
+        this.#insertCleanupRunStatement = this.#database.prepare(`
+      INSERT INTO cleanup_runs(
+        scan_id,
+        cleanup_uuid,
+        cleanup_started_at,
+        github_actions_run_url,
+        dry_run,
+        planner_inputs_json,
+        direct_target_tag_count,
+        direct_target_root_count,
+        delete_root_candidate_count,
+        untag_only_root_count,
+        fully_deletable_root_count,
+        blocked_delete_root_count,
+        protected_root_count
+      )
+      VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
     }
     persistCleanupRun(scanId, plan, options) {
         return this.#database.transaction(() => {
             const cleanupRunId = this.#insertCleanupRun(scanId, plan, options);
+            for (const tag of plan.directTargetTags) {
+                this.#insertSelectedTagStatement.run(cleanupRunId, scanId, tag);
+            }
             for (const rootDecision of plan.rootDecisions) {
-                this.#database
-                    .prepare(`
-              INSERT INTO cleanup_root_decisions(
-                cleanup_run_id,
-                scan_id,
-                digest,
-                selection_mode,
-                selection_reason,
-                validation_status,
-                validation_reason_code,
-                validation_reason,
-                blocking_digest,
-                overlap_digest
-              )
-              VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-            `)
-                    .run(cleanupRunId, scanId, rootDecision.digest, rootDecision.selectionMode, rootDecision.selectionReason, rootDecision.validationStatus, rootDecision.validationReasonCode, rootDecision.validationReason, rootDecision.blockingDigest ?? null, rootDecision.overlapDigest ?? null);
+                this.#insertRootDecisionStatement.run(cleanupRunId, scanId, rootDecision.digest, rootDecision.selectionMode, rootDecision.selectionReason, rootDecision.validationStatus, rootDecision.validationReasonCode, rootDecision.validationReason, rootDecision.blockingDigest ?? null, rootDecision.overlapDigest ?? null);
             }
             for (const protectedRoot of plan.protectedRoots) {
                 for (const block of protectedRoot.blocks) {
-                    this.#database
-                        .prepare(`
-                INSERT INTO cleanup_protected_root_blocks(
-                  cleanup_run_id,
-                  scan_id,
-                  protected_digest,
-                  blocked_digest,
-                  block_reason_code,
-                  overlap_digest
-                )
-                VALUES(?, ?, ?, ?, ?, ?)
-              `)
-                        .run(cleanupRunId, scanId, protectedRoot.digest, block.blockedDigest, block.blockReasonCode, block.overlapDigest);
+                    this.#insertProtectedRootBlockStatement.run(cleanupRunId, scanId, protectedRoot.digest, block.blockedDigest, block.blockReasonCode, block.overlapDigest);
                 }
             }
             return cleanupRunId;
         })();
     }
     #insertCleanupRun(scanId, plan, options) {
-        const result = this.#database
-            .prepare(`
-          INSERT INTO cleanup_runs(
-            scan_id,
-            cleanup_uuid,
-            cleanup_started_at,
-            github_actions_run_url,
-            dry_run,
-            planner_inputs_json,
-            direct_target_tag_count,
-            direct_target_root_count,
-            delete_root_candidate_count,
-            untag_only_root_count,
-            fully_deletable_root_count,
-            blocked_delete_root_count,
-            protected_root_count
-          )
-          VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        `)
-            .run(scanId, randomUUID(), options.cleanupStartedAt, resolveGitHubActionsRunUrl(), options.dryRun ? 1 : 0, JSON.stringify(plan.plannerInputs), plan.validationSummary.directTargetTagCount, plan.validationSummary.directTargetRootCount, plan.validationSummary.deleteRootCandidateCount, plan.validationSummary.untagOnlyRootCount, plan.validationSummary.fullyDeletableRootCount, plan.validationSummary.blockedDeleteRootCount, plan.validationSummary.protectedRootCount);
+        const directTargetTagCount = plan.directTargetTags.length;
+        const directTargetRootCount = plan.directTargetRoots.length;
+        const deleteRootCandidateCount = plan.directTargetRoots.filter((root) => root.selectionMode === "delete-root").length;
+        const untagOnlyRootCount = plan.rootDecisions.filter((decision) => decision.validationStatus === "untag-only").length;
+        const fullyDeletableRootCount = plan.fullyDeletableRoots.length;
+        const blockedDeleteRootCount = plan.rootDecisions.filter((decision) => decision.validationStatus === "blocked").length;
+        const protectedRootCount = plan.protectedRoots.length;
+        const result = this.#insertCleanupRunStatement.run(scanId, randomUUID(), options.cleanupStartedAt, resolveGitHubActionsRunUrl(), options.dryRun ? 1 : 0, JSON.stringify(plan.plannerInputs), directTargetTagCount, directTargetRootCount, deleteRootCandidateCount, untagOnlyRootCount, fullyDeletableRootCount, blockedDeleteRootCount, protectedRootCount);
         return Number(result.lastInsertRowid);
     }
 }