Archive on Destroy for Gitlab Provider

[maikelnight]

What problem are you facing?

We realized that the option archive on destroy seems not been implemented yet, as for example its possible in terraform ( see: https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs/resources/project ).
This is a necessary option in enterprise where delete is not allowed due to regulatory frameworks.

How could Crossplane help solve your problem?

It would be a proper solution if this option would be possible in the native crossplane provider too.
thanks and regards

[markussiebert]

Proposal: archived as a reconciled project property (not a delete behaviour)

This is my opinion on how to approach this, and I'm very happy to discuss it —
nothing here is set in stone.

After looking into this, I want to implement archived as a normal, reconciled
property of the Project resource — mirroring Terraform's archived attribute —
rather than as a special "archive instead of delete" behaviour.

Why not overload delete?

Crossplane's Delete contract requires that, after deletion, the external
resource no longer exists (so Observe reports it gone and the finalizer can be
removed). An archived project still exists, so an "archive on destroy" hook would
leave Observe perpetually finding the project and the managed resource would
never finalize cleanly. Overloading delete fights the runtime's model.

The idiomatic Crossplane story

The "delete is not allowed in our enterprise" requirement is actually a strong
argument for making archived a property and leaning on Crossplane's existing
deletion/management policies:

1. Set archived: true on the Project spec — the provider reconciles the
   project into the archived state.
2. Confirm status.atProvider.archived == true.
3. Remove the managed resource with spec.deletionPolicy: Orphan (or equivalent
   managementPolicies that exclude Delete), so Crossplane stops managing it
   without ever calling the GitLab delete API.

This cleanly separates "what state should the project be in" (archived) from
"what happens to the K8s object" (orphan, never delete) — and guarantees the
GitLab delete endpoint is never hit, satisfying the regulatory constraint.

Reconcile ordering & the read-only effect of archiving

GitLab makes an archived project read-only — the edit endpoint and most
sub-resource endpoints reject writes while the project is archived. Two
consequences:

• The Project controller itself will, when reconciling an archived project
  that also has other drift, need to unarchive → apply edits → re-archive so the
  managed resource still converges to the desired state.
• Related resources (members, variables, hooks, deployTokens,
  deployKeys, badges, pipelineSchedules, protectedBranches,
  protectedEnvironments, approvalRules, runners, projectShareGroups,
  integrations, ...) are each their own managed resource. Against an archived
  project their reconciles will conflict (read-only). This is inherent to
  GitLab's archive behaviour, not provider-specific.

Planned guidance (document-only, no cross-controller coupling): unarchive the
project first if you need to change it or any of its related resources. Archived
projects will produce conflicts the same way for the project and all related
resources. Clean teardown of an archived project therefore also means orphaning
its related resources, not only the project.

Field design

• New spec field archived *bool on ProjectParameters (optional, tri-state,
  consistent with the other project fields).
• Reconciled via the dedicated GitLab endpoints POST /projects/:id/archive and
  POST /projects/:id/unarchive (go-gitlab ArchiveProject / UnarchiveProject).
  Note: the Edit project endpoint does not toggle archive state, so this
  cannot be folded into the existing edit-options flow — it needs its own call in
  Update().
• Late-initialized like the other project fields: the observed archive state
  is written into the spec on adoption. Consequence to be explicit about: once
  adopted, archived is drift-corrected like any other managed field — if a
  project is archived (or unarchived) out-of-band, the provider will revert it to
  the spec value. In particular, an active project adopted by Crossplane may be
  automatically unarchived if someone archives it outside Crossplane. This is
  consistent with how every other late-initialized field behaves.

Implementation outline

• archived *bool added to ProjectParameters in the namespaced source only;
  the cluster-scoped equivalent is regenerated via make generate
  (hack/generate-cluster-scope.go), not hand-edited.
• Add ArchiveProject / UnarchiveProject to the projects Client interface +
  fake mock.
• Update(): when other properties drift on an archived project, unarchive →
  edit → re-archive; otherwise reconcile the archived bit on its own.
• isProjectUpToDate: compare archived state (via observed atProvider.archived).
• Late-initialize archived from the observed project.
• Unit tests for create/observe/update covering archive, unarchive, and the
  unarchive→edit→re-archive path; add an example manifest demonstrating the
  archived: true + deletionPolicy: Orphan retirement workflow.
• Both API trees ship in parity (cluster via generation).

---

Again, this is my proposed direction rather than a final decision — feedback and
counter-arguments welcome, especially on the reconcile-ordering behaviour
(unarchive → edit → re-archive) and the late-initialization / drift-correction
semantics.

[Lindmeier]

I’ll admit we were initially pretty stuck on the Terraform paradigm of using "archive on destroy." However, after reading through your reasoning, I completely agree with your approach. Since the infrastructure object (the GitLab project) remains intact in an archived state, making it a standard, reconciled property rather than overloading Crossplane's delete lifecycle is definitely the most accurate way to reflect the API's behavior.

I am also fully on board with your thoughts on the late-initialization and drift-correction semantics.

Regarding the Reconcile Ordering & Read-Only Effect: I do have one reservation about the proposed unarchive → edit → re-archive flow. From my point of view, attempting to reconcile an archived project — or more specifically, the sub-resources of an archived project — should simply result in a Not Synced (Synced: False) state.
The project controller shouldn't automatically unarchive and re-archive the resource under the hood. Since the GitLab UI and API don't perform this action automatically, the Crossplane provider shouldn't abstract that restriction away either. Exposing the sync failure feels like a safer, more transparent reflection of GitLab's native constraints, forcing the user to intentionally declare the unarchived state if they want to make edits.

[markussiebert]

Thanks @maikelnight for raising this and @Lindmeier for the detailed feedback. Here's where the discussion has landed on the design.

Direction

Archive should be a normal reconciled property, not an "archive on destroy" delete hook. The GitLab project stays intact in an archived state, so it belongs in the spec, not in Crossplane's delete lifecycle. Retiring a project would then look like:

spec:
  forProvider:
    archived: true
  deletionPolicy: Orphan   # keep the archived project when the MR is deleted

• New spec field archived *bool on ProjectParameters (tri-state, late-initialized from the observed state, like the other project fields).
• Reconciled via the dedicated endpoints POST /projects/:id/archive / unarchive (the Edit project call does not reliably toggle archive state, so it can't be folded into the edit flow).

Agreed behaviour

1. No implicit unarchive→edit→re-archive. Agreeing with @Lindmeier: GitLab makes archived projects read-only and we shouldn't abstract that away. If a project is archived and other fields drift, the resource should go Synced: False and the user must intentionally set archived: false to make edits. This is also consistent with how the project's sub-resources behave (see #3).

2. The provider is authoritative on the archived bit, and archive runs last. archived is drift-corrected in both directions:

• spec archived: false + observed archived → unarchive (honoring the declared state — not a hidden toggle to sneak an edit through).
• spec archived: true + observed active → apply any other outstanding updates first, then archive as the final operation.

Consequence to document: a project archived out-of-band while the spec says archived: false will be unarchived on the next reconcile, consistent with every other late-initialized field.

The only error case is therefore: project already archived, spec keeps it archived, and other fields drift → Synced: False (no auto-unarchive).

3. No cross-controller coupling. Related resources (members, variables, hooks, …) would not be made archive-aware. While a project is archived, changes to its sub-resources may fail and surface Synced: False. Clean teardown of an archived project therefore also means orphaning its related resources. This should be documented rather than worked around.

Contributions welcome

This is a community-driven provider, so we'd be very happy to see a PR implementing this along the lines above — including client ArchiveProject/UnarchiveProject wiring, the Update() ordering (edits first, archive last), late-init + drift-correction, unit tests, and an example manifest for the archived: true + deletionPolicy: Orphan workflow. Please shout on the issue if you'd like to pick it up or want to discuss any of the decisions further.