Skip to content

Enhancement: Support tag references in referrer list with automatic digest resolution #46

Closed
#68
Closed
Enhancement: Support tag references in referrer list with automatic digest resolution#46
#68
Labels
enhancementNew feature or request

Description

@toddysm
toddysm
opened on Mar 14, 2026

Description

regshape referrer list currently requires a digest reference (registry/repo@sha256:...) and rejects tag references with exit code 2. This is because the OCI Referrers API endpoint (GET /v2/<name>/referrers/<digest>) requires a digest.

However, users most commonly work with tags rather than digests. The command should accept tag references and automatically resolve them to a digest via a HEAD request before querying the referrers API.

Proposed Behavior

When --image-ref contains a tag reference (e.g. registry/repo:v1.0), the command should:

  1. Issue HEAD /v2/<name>/manifests/<tag> to resolve the tag to a digest (via the Docker-Content-Digest response header)
  2. Use the resolved digest to call GET /v2/<name>/referrers/<digest>
  3. Proceed as normal with the referrer results

When --image-ref already contains a digest, behavior is unchanged.

Acceptance Criteria

  • regshape referrer list -i registry/repo:tag resolves the tag and lists referrers
  • regshape referrer list -i registry/repo@sha256:... continues to work as before (no regression)
  • Tag resolution failure (e.g. tag not found) produces a clear error with exit code 1
  • The --json, --all, --artifact-type, and --output flags work with tag references
  • Help text and --image-ref description updated to reflect tag support
  • Unit tests cover: tag resolution happy path, tag not found error, digest passthrough unchanged
  • CLI spec (specs/cli/referrer.md) updated to document tag support

Files to Create/Modify

CLI layer

  • src/regshape/cli/referrer.py — Remove the digest-only guard; add tag-to-digest resolution using head_manifest before calling list_referrers/list_referrers_all

Library layer

No changes needed — libs/referrers/operations.py already accepts a digest string, and libs/manifests/operations.py already provides head_manifest(client, repo, reference, accept) which returns (digest, media_type, size).

Tests

  • src/regshape/tests/test_referrer_cli.py — Add tests for tag resolution, update test_tag_reference_rejected_with_exit_code_2 to expect success instead of rejection

Specs

  • specs/cli/referrer.md — Update accepted formats table and description

Implementation Notes

The tag-to-digest resolution requires a single additional HEAD request. The head_manifest function from libs/manifests already handles this:

from regshape.libs.manifests import head_manifest
from regshape.libs.models.mediatype import ALL_MANIFEST_MEDIA_TYPES

accept = ",".join(sorted(ALL_MANIFEST_MEDIA_TYPES))
digest, _, _ = head_manifest(client, repo, tag, accept)
# Now use digest for the referrers API call

The guard block that currently rejects tags:

if not reference.startswith("sha256:") and not reference.startswith("sha512:"):
    emit_error(...)

should be replaced with a resolution step that calls head_manifest to obtain the digest.

References

  • specs/cli/referrer.md — Current CLI spec
  • specs/operations/referrers.md — Referrers operations spec
  • OCI Distribution Spec: Referrers API requires a digest in the URL path

Activity

  1. toddysm
    added
    enhancementNew feature or request
    on Mar 14, 2026

  2. toddysm commented on Oct 28, 2026

    @toddysm
    toddysm
    on Oct 28, 2026
    OwnerAuthor

    Implementation checkpoint — in progress

    Implementing the issue scope with hosted testing, continuing the mode selected for this instance. Owner: fd2ca782-7ed9-4986-98b4-1168ece9ee3d.
    Branch: feature/referrers-by-tag/issue-46-fd2ca782.
    Owned worktree: /Users/toddysm/Documents/Development/regshape-fe-fd2ca782-referrers.
    Base: 024c15bc7da136448a3856de59fe30deea0a49a5. Changes are currently local and uncommitted; no merge is authorized.

    The command reuses head_manifest to resolve explicit/default tags, preserves SHA-256/SHA-512 digest passthrough, and reports missing digest headers or lookup failures before querying referrers or writing output. Tests cover option combinations, failure paths, and actual manifest/referrer library wiring; the CLI specification is updated.

    This repository previously had only a release workflow, so this change adds hosted pytest validation for the declared Python 3.10/3.11/3.12 versions and documents the test command. No publishing/release changes are included. Next: focused validation, self-review, and one unmerged pull request with automated review.

  3. toddysm commented on Oct 28, 2026

    @toddysm
    toddysm
    on Oct 28, 2026
    OwnerAuthor

    Implementation checkpoint — in review

    Opened #68, targeting main. Pushed commit: 90f5d03.

    The requested tag-resolution behavior, option compatibility, failure handling, command help/spec updates, and regression tests are implemented. The new hosted test workflow covers the declared Python 3.10/3.11/3.12 versions without changing release automation.

    Testing mode: hosted. Local validation: 92 focused tests passed on Python 3.12.4; scoped Ruff, Bandit, mypy (isolated request stubs), actionlint, and whitespace checks passed. Self-review found no blocking issues. Hosted full-suite checks and automated review are being monitored; no hosted success is claimed yet.

    Owner: fd2ca782-7ed9-4986-98b4-1168ece9ee3d; branch feature/referrers-by-tag/issue-46-fd2ca782; worktree /Users/toddysm/Documents/Development/regshape-fe-fd2ca782-referrers. Working tree clean and all changes pushed. The pull request remains unmerged; Project updates are unavailable with current permissions.

  4. toddysm commented on Oct 28, 2026

    @toddysm
    toddysm
    on Oct 28, 2026
    OwnerAuthor

    Implementation checkpoint — feature implemented, full validation blocked

    Pull request: #68.
    Last pushed/tested head: 90f5d037976734a1137ae71430eb780475ab66df.
    Testing mode: hosted.

    The tag-resolution acceptance cases pass: 92 focused CLI/referrer/manifest tests locally, plus scoped Ruff, Bandit, mypy, actionlint, and whitespace checks. Copilot review completed with no findings or unresolved threads; CodeQL checks passed.

    The newly added full-suite hosted run 40770926831 returned 1062 passed, 5 failed on each of Python 3.10, 3.11, and 3.12. Four failures concern catalog pagination tests and one concerns the expected request count for a transport 401 response without an authentication challenge. All five were reproduced on unchanged main (024c15bc7da136448a3856de59fe30deea0a49a5) in a separate baseline worktree: 5 failed, 6 passed across the affected test classes. Exact selectors and evidence are recorded in the pull request.

    These are pre-existing failures outside the #46 change. No tests were skipped or disabled, no unrelated catalog/transport fixes were made, and no green full-suite result is claimed. The pull request and issue remain open. Next step: obtain user guidance on fixing the baseline failures separately before completing the validation gate.

    Owner: fd2ca782-7ed9-4986-98b4-1168ece9ee3d.
    Branch: feature/referrers-by-tag/issue-46-fd2ca782.
    Owned worktree: /Users/toddysm/Documents/Development/regshape-fe-fd2ca782-referrers.
    All implementation changes are committed and pushed; working tree clean. The feature branch/worktree/claim are retained. The clean temporary baseline worktree and isolated type-checking environment can be removed after this checkpoint. No merge is authorized; Project updates remain unavailable with current permissions.

  5. toddysm commented on Oct 29, 2026

    @toddysm
    toddysm
    on Oct 29, 2026
    OwnerAuthor

    Baseline repair checkpoint

    A separate test-only repair pull request #71 now addresses the five baseline failures blocking #68. Head: 51a8b97cc1587265414862ae3c6af2c8d02af62f. It corrects catalog mock response tracking and the authentication probe expectation without changing production code or weakening pagination assertions. All 1047 baseline tests pass locally; hosted checks/review are pending.

    The #68 branch remains unchanged and unmerged. Once the repair is merged with authorization, integrate main and rerun the feature checks. Testing mode: hosted; owner instance fd2ca782-7ed9-4986-98b4-1168ece9ee3d; repair worktree /Users/toddysm/Documents/Development/regshape-fe-fd2ca782-baseline on feature/test-baseline/repair-mocks-fd2ca782. No merge or release is authorized.

  6. toddysm commented on Oct 29, 2026

    @toddysm
    toddysm
    on Oct 29, 2026
    OwnerAuthor

    Baseline repair checkpoint — validated, awaiting merge

    Test-only repair #71, head 51a8b97cc1587265414862ae3c6af2c8d02af62f, passes all 1047 tests on Python 3.10, 3.11, and 3.12 in hosted run 40948711011. CodeQL passes and Copilot review recommends approval with no findings or unresolved threads. No production behavior was changed.

    The repair remains unmerged. #68 has not been modified, and its previous failing checks remain historical evidence until main is updated and its checks rerun. Next step: authorize merging #71, then integrate main into #68.

    Owner fd2ca782-7ed9-4986-98b4-1168ece9ee3d; testing mode hosted; repair branch feature/test-baseline/repair-mocks-fd2ca782; worktree /Users/toddysm/Documents/Development/regshape-fe-fd2ca782-baseline. Clean, fully pushed, and retained for review. No merge or release was performed.

  7. toddysm commented on Oct 29, 2026

    @toddysm
    toddysm
    on Oct 29, 2026
    OwnerAuthor

    Baseline repair merge checkpoint

    #71 was merged with user authorization into main at 6d2c188b07e6211263b6ba3518eeee97bd2bae20 (verified GitHub signature). Copilot/Codex reviews had no findings or unresolved threads, and pre-merge checks passed. The merged tree matches the tested head exactly.

    Post-merge run 40952280635 passed all 1047 tests on Python 3.10, 3.11, and 3.12. #68 remains unchanged and unmerged; its old failures are not current-main failures. Next step is to authorize integrating main into its branch and rerunning feature checks/review.

    Owner fd2ca782-7ed9-4986-98b4-1168ece9ee3d; testing mode hosted; repair branch feature/test-baseline/repair-mocks-fd2ca782; worktree /Users/toddysm/Documents/Development/regshape-fe-fd2ca782-baseline. Clean, fully pushed, and retained. No release or feature-branch update was performed.

  8. toddysm commented on Oct 29, 2026

    @toddysm
    toddysm
    on Oct 29, 2026
    OwnerAuthor

    Refresh checkpoint — repaired main integrated

    User-authorized continuation of #68. Integrated main 6d2c188b07e6211263b6ba3518eeee97bd2bae20 with a normal merge commit, without rewriting history or changing the feature scope.

    New pushed head: e5d1adad3be0efb4bd1dc32cd17135f4e7634507. Full local suite: 1071 passed. Hosted validation and current-head Copilot/Codex reviews are being refreshed; the old baseline failures are historical, not a result for this new head.

    Owner fd2ca782-7ed9-4986-98b4-1168ece9ee3d; testing mode hosted; branch feature/referrers-by-tag/issue-46-fd2ca782; worktree /Users/toddysm/Documents/Development/regshape-fe-fd2ca782-referrers. Changes committed and pushed. The pull request remains open; no merge into main, release, or branch deletion is authorized in this step.

  9. toddysm commented on Oct 29, 2026

    @toddysm
    toddysm
    on Oct 29, 2026
    OwnerAuthor

    Refresh checkpoint — validated and ready for merge approval

    #68 now includes repaired main 6d2c188 at head e5d1adad3be0efb4bd1dc32cd17135f4e7634507.

    Full local suite: 1071 passed. Hosted run 40955354879 passed 1071 tests on each of Python 3.10/3.11/3.12. CodeQL passed. Copilot and Codex both completed review of this head with no findings or unresolved threads. The former baseline blocker is resolved; tests were not skipped or disabled.

    Testing mode: hosted. Owner fd2ca782-7ed9-4986-98b4-1168ece9ee3d; branch feature/referrers-by-tag/issue-46-fd2ca782; worktree /Users/toddysm/Documents/Development/regshape-fe-fd2ca782-referrers. Clean and fully pushed, retained for review. The pull request and issue remain open until an explicitly authorized merge; no merge or release was performed.

  10. toddysm
    closed this as completedin #68on Oct 30, 2026

  11. toddysm commented on Oct 30, 2026

    @toddysm
    toddysm
    on Oct 30, 2026
    OwnerAuthor

    Merged checkpoint

    With owner authorization, #68 was squash-merged into main as 5fdd598a3233d5cb53b4380c22f104e4a91bf439. Issue #46 is closed. The reviewed head was e5d1adad3be0efb4bd1dc32cd17135f4e7634507, with 1071 tests passing on each hosted Python version, CodeQL green, both reviewers clear, and no unresolved threads. Current main and branch protections were refreshed before the normal merge; no bypass was used.

    Instance fd2ca782-7ed9-4986-98b4-1168ece9ee3d retains the clean, fully pushed branch feature/referrers-by-tag/issue-46-fd2ca782 and worktree /Users/toddysm/Documents/Development/regshape-fe-fd2ca782-referrers. No branch/worktree cleanup or release was requested or performed. Next step is integrating this merged main into #70 and validating the combined features before its separately authorized merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions