docs(specs): promote the artifact deletes in S14 and S06

Summary

monolith/2026-09-01-artifact-delete-surface gates Steps 6 through 28 on a spec promotion MR. This is that MR. It covers the first slice's single deletes and the deferred bulk slice, so both Phase 1 prohibitions invert once and neither spec is left self-contradictory.

The specs describe the delete surface as it is on gitlab-org/gitlab master at 786e3c4a44c2 where it has shipped, and specify it where it has not:

  • Shipped at 786e3c4a44c2: ArtifactRegistryVersionDelete, ArtifactRegistryManifestDelete, ArtifactRegistryContainerTagDelete, ArtifactRegistryNpmDistTagDelete; the client's delete_version, delete_manifest, delete_container_tag, and delete_npm_dist_tag; the version and manifest row deletes; the version list heading's artifact delete; and the version-detail kebab's Delete version.
  • Specified here, not shipped: the two bulk mutations over an ids list, the two bulk client methods (drafts at gitlab!256212 and gitlab!256223, which also carry delete_all: and bulk_delete_container_tags this spec does not specify), page-scoped multi-select with Delete selected, npm dist-tag removal on version detail, the container page's Delete manifest, and the removed-artifact redirect.

What each spec gains

monolith/S14 (version list)

  • ### Mutations: five mutations, the four properties they share with ArtifactRegistryArtifactDelete, the shared error mapping, and the two shipped wrong-format refusal forms (payload errors for the version delete, a top-level argument error for the manifest and container tag deletes).
  • #### The bulk selector: the ids list only, with no whole-collection branch and no bulk tag mutation in the schema; the ids → version_ids: / digests: mapping; and the 413, 503, and Retry-After bounds as AR serves them, with the 413 claim scoped to what the view sends.
  • ## Ruby client: the five write methods, local list refusals, the retry exclusion, and the 409 parents allowlist behaviour.
  • ### Connections: the 20-row page cap, with its source and paging cost.
  • ### Delete actions: per-target confirmation copy, the single-vs-bulk meaning of the 202 with its S17 source, eviction, the empty-page re-read, the removed-artifact redirect keyed on a null read after the view's own delete (aligned with gitlab-org/gitlab#631424 and AR#951), and why Delete manifest stays enabled.
  • ### Multi-select and bulk delete: page-scoped selection, Delete selected only, the unreachable 1000 cap at a 20-row page, and the silent skip of a child an outside index references.
  • No delete renders on a remote repository reached by deep link.
  • RSpec and request-spec acceptance criteria for every write, and Jest criteria for the failure outcomes.
  • Phase 2 and Resolutions edits that change a stated reason: the Tags and Referrers rows now say what the manifests list serves (tags_preview, parents_preview), a new row covers the "referenced by" parent link, the Tags Resolution gives the current reason for the deferral, and the S05 fan-out bullet now reads "one AR request per parent row plus the parent read".

monolith/S06 (version detail)

  • ### Mutations: the two mutations shared with S14, and ArtifactRegistryNpmDistTagDelete, which checks format and kind before any AR call.
  • ### Header: Delete version, npm dist-tag removal, and the container page's Delete manifest; no delete on a remote repository; and the package or image re-read that decides where a delete lands, including on a failed re-read.
  • The container page's Phase 2 rows gain Delete manifest beside the Download manifest row, both waiting on that page's kebab.

monolith/S05 (repository detail)

  • ArtifactRegistryArtifactDelete stays kind-neutral.
  • ArtifactRegistryRepositoryArtifactsDelete must refuse a repository that is not remote, server-side. Without that refusal, a direct GraphQL call on a hosted repository permanently deletes every artifact. The shipped mutation checks no kind; the implementation is tracked in gitlab-org/gitlab#632065. This reverses 626611's "no kind guard" ruling for the repository clear only, and notes on 626611 and 627172 record that.
  • The hosted Delete package / Delete image confirmation and success outcome.

monolith/S02 (Ruby client): the retry policy is corrected to the shipped one. The connection retries GET only and has excluded DELETE since gitlab-org/gitlab 58f78d3dff79, which S14 and S06 rely on. S02 still said DELETE was retried, which GitLab Duo flagged as a contradiction.

monolith/S02 also says the per-attempt error callback fires once per attempt, and records that delete_repository now gets one attempt.

monolith/S15 and docs/specs/README.md: the rows that still carried delete-file, the files-tab bulk delete, the Phase 1 "no kebab" line, and the "no layer serves" tag claim are brought in line. S15's shipped-control paragraph is re-measured at 786e3c4a44c2: four of the five shipped deletes read the verdict, and only version detail's Delete version does not.

Plan mismatches left for a docs(plans) follow-up

The spec now agrees with the plan on the dist-tag control reading kind (Steps 18 and 26), the "cannot be undone" copy (Step 11), and an ids-only bulk bar (Step 14). These mismatches remain in the plan:

  • Files: #delete_file, #bulk_delete_files, ArtifactRegistryFileDelete, and ArtifactRegistryFilesBulkDelete in Steps 1, 4, 6, and 9, and Steps 17 and 19 whole. Per-file delete is out of the product. delete_file removal is gitlab!253712.
  • Step 14: "a selection over the cap disables submission and names the cap". With a 20-row page no selection reaches the 1000 cap, so the spec writes no cap message.
  • Step 11 and Step 12: node eviction "with no refetch". The spec accepts a list re-read after a single delete, because a single delete writes before its 202. The shipped versions table re-reads.
  • Step 15: "a per-manifest tags read, which no layer serves". AR serves tags_preview on the list and the full tags on manifest detail.
  • Steps 4, 9, and 10: delete_all:, bulk_delete_container_tags, ArtifactRegistryBulkDeleteSelectorInput, and ArtifactRegistryContainerTagsBulkDelete. The spec now has no whole-collection branch and no bulk tag mutation.

UX decisions recorded in Resolutions

Each can be overturned without reopening the wire contract.

  • Manage-tags removes one tag per action.
  • Bulk selection is page-scoped, and the schema carries no whole-collection branch until a surface and its confirmation exist.

Reviewable size

1,096 insertions and 233 deletions across six files at 909eb60b3, over the 500-LOC guideline. The two Phase 1 prohibitions are the gate, one per spec, and inverting one without the other leaves half the frontend forbidden. S05 and S15 move because the promotion falsifies statements in them, and S02 because its retry text contradicted the code S14 and S06 cite.

File Insertions Deletions
docs/specs/monolith/S14-version-list.md 667 110
docs/specs/monolith/S06-version-detail.md 312 62
docs/specs/monolith/S05-repository-detail.md 75 25
docs/specs/monolith/S15-permission-gated-controls.md 27 22
docs/specs/monolith/S02-ar-ruby-client.md 13 12
docs/specs/README.md 2 2

Verification

  • markdownlint-cli2, vale --minAlertLevel=error, and lychee --offline --include-fragments on all six files: 0 errors.
  • Monolith facts were checked at 786e3c4a44c2:
    • max_page_size: 20 on the versions and manifests connections and on the parent packages and images connections, and the resolvers' FieldCallCount budgets, unchanged at 949f666e5fb2;
    • which shipped delete controls call permissionAllows;
    • renders_errors.rb, MAX_RENDERED_PARENTS = 10, the parents allowlist, and the retry allowlist;
    • the per-mutation format and kind checks;
    • the modal copy.
  • AR facts were checked at origin/main:
    • parents_preview and tags_preview on ContainerManifest;
    • GET .../manifests/{digest} in v1.yaml and handler.go;
    • Retry-After only in denial.go;
    • the \uXXXX escape case in the bulk ceilings;
    • the single-delete write paths;
    • npm last-version package removal;
    • tag delete removing the tag row only.

E2E scenario impact

None. artifact_registry_ui is dark for every step of the plan this MR unblocks, and no scenario in docs/testing/e2e/ is added or changed. The flag's own enablement is tracked at gitlab#605113.

Related to gitlab-org/gitlab#627172

Edited by Narendran

Merge request reports

Loading
Loading