Expose the `Organizations::RestoreService` (from #599343) through a new `OrganizationRestore` GraphQL mutation, transitioning a soft-deleted organization back to `active`. Admin-only. ## Dependency > **Update (2026-07-15):** #599343 is now **complete and merged** (via !239973), so this issue is **no longer blocked** and can start now. `Organizations::RestoreService` and the `:restore_organization` policy ability both exist. ~~Blocked by #599343, which must land first since it provides:~~ - `Organizations::RestoreService` (the service this mutation calls), and - the `:restore_organization` policy ability (admin-only) used for `authorize`. ## Background The existing organization mutations live in `app/graphql/mutations/organizations/` (`Create`, `Update`, `OrganizationUsers::Update`) and are mounted in `app/graphql/types/mutation_type.rb` behind an `experiment` milestone marker. All of them declare both a declarative-policy `authorize` and an `authorize_granular_token` permission. There is no delete/soft-delete/restore mutation yet, so `OrganizationRestore` is the first state-transition mutation in this namespace. ## Implementation plan ### 1. Mutation — `app/graphql/mutations/organizations/restore.rb` Inherit directly from `BaseMutation` (not `Mutations::Organizations::Base`, which adds `description`/`avatar` arguments that don't apply to restore): ```ruby # frozen_string_literal: true module Mutations module Organizations class Restore < BaseMutation graphql_name 'OrganizationRestore' authorize :restore_organization authorize_granular_token permissions: :restore_organization, boundary: :instance, boundary_type: :instance argument :id, Types::GlobalIDType[::Organizations::Organization], required: true, description: 'ID of the organization to restore.' field :organization, ::Types::Organizations::OrganizationType, null: true, description: 'Organization after mutation.' def resolve(id:) organization = authorized_find!(id: id) result = ::Organizations::RestoreService.new( organization, current_user: current_user ).execute { organization: result.payload[:organization], errors: result.errors } end end end end ``` Notes: - `authorized_find!(id:)` resolves the GlobalID and runs the `:restore_organization` policy check, returning a top-level error for unauthorized callers before the service runs. - The `:restore_organization` policy ability is admin-only (defined in #599343), so non-admin owners are rejected here even though they can soft-delete. - Service-level errors (e.g. organization not soft-deleted) surface in the mutation's `errors` array via `result.errors`, matching `Create`/`Update`. ### 2. Granular token permission registry All sibling org mutations declare `authorize_granular_token`, which requires the permission to be registered. Add: `config/authz/permissions/organization/restore.yml`: ```yaml --- name: restore_organization description: Grants the ability to restore soft-deleted organizations ``` `config/authz/permission_groups/assignable_permissions/organizations/organization/restore.yml`: ```yaml --- name: restore_organization description: Grants the ability to restore soft-deleted organizations boundaries: - instance available_for: - granular_access_token permissions: - restore_organization ``` (Same name shared by the policy ability and granular permission — consistent with how `create_organization` is used by `OrganizationCreate`.) > **Note:** Verify these file locations, keys, and boundary values at build time against a sibling mutation (e.g. `create_organization`) in case the expected format has changed. ### 3. Mount the mutation — `app/graphql/types/mutation_type.rb` Alongside the other org mutations (after `Mutations::Organizations::OrganizationUsers::Update`), behind the current milestone's experiment marker: ```ruby mount_mutation Mutations::Organizations::Restore, experiment: { milestone: '19.3' } ``` ### 4. Regenerate GraphQL docs & schema ``` bundle exec rake gitlab:graphql:compile_docs ``` This updates `doc/api/graphql/reference/_index.md` (adds `Mutation.organizationRestore` + `OrganizationRestoreInput`/`OrganizationRestorePayload`) and dumps the schema. CI's `graphql-verify` job fails if these are stale. ### 5. Request spec — `spec/requests/api/graphql/mutations/organizations/restore_spec.rb` Mirror the existing org mutation request specs, covering: - Unauthenticated / non-admin user → top-level authorization error, organization unchanged. - Admin restoring a `soft_deleted` organization → `soft_deleted → active`, response returns the organization with empty `errors`. - Admin restoring a non-`soft_deleted` organization → `errors` populated by the service, no state change. - Invalid/unknown GlobalID → resource-not-available error. ## Out of scope - The `Organizations::RestoreService` itself - #599343+ - Admin Area UI / button to trigger restore — separate issue. - A soft-delete GraphQL mutation - https://gitlab.com/gitlab-org/gitlab/-/work_items/594313+ ## Acceptance criteria - [ ] `OrganizationRestore` mutation exists and calls `Organizations::RestoreService`. - [ ] The mutation is authorized via the admin-only `:restore_organization` ability and registered as a granular-token permission, consistent with sibling org mutations. - [ ] Restoring a soft-deleted organization transitions it to `active` and returns it in the payload. - [ ] Service validation failures surface in the mutation `errors` array. - [ ] The mutation is mounted behind an `experiment` milestone marker. - [ ] GraphQL reference docs and schema are regenerated. - [ ] Request spec covers authorization, success, validation failure, and not-found cases.