feat(groups): add ServiceAccountAccessToken managed resource (#326)

* feat(groups): add ServiceAccountAccessToken managed resource

Adds a group-scoped ServiceAccountAccessToken managed resource that manages
the personal access token of a group service account.

Owner mode (default): the ProviderConfig is a group owner and the token is
managed via the service-account endpoints:

- Create  -> Groups.CreateServiceAccountPersonalAccessToken
- Observe -> Groups.ListServiceAccountPersonalAccessTokens (match by token id)
- Rotate  -> Groups.RotateServiceAccountPersonalAccessToken
- Revoke  -> Groups.RevokeServiceAccountPersonalAccessToken

Self-managed mode: when the referenced ProviderConfig authenticates with the
very token this resource writes to its connection secret (detected when the
PersonalAccessToken credential secretRef matches writeConnectionSecretToRef by
namespace, name and key), the provider acts as the service account itself and
uses the self endpoints instead:

- Observe -> GET /personal_access_tokens/self (self-inform; external name is
  auto-adopted from the response)
- Rotate  -> RotatePersonalAccessTokenSelf
- Revoke  -> RevokePersonalAccessTokenSelf

This enables a self-sustaining loop of short-lived, self-rotating tokens used to
reconcile a group. A dead self-token surfaces as a clear terminal error
(reseed the credentials secret). A SelfManaged status condition reports the
detected mode.

The external name is the token id and the token value is written to the
connection secret on create/rotate. Rotation, expiresAt/renewalPeriodDays and
renewBeforeDays semantics match the group AccessToken controller. groupId,
serviceAccountId, name and scopes are immutable (enforced via CEL); the
rotation-timing fields stay mutable.

Fixes #324

Signed-off-by: Markus Siebert <markus.siebert@deutschebahn.com>

* fix(groups): address ServiceAccountAccessToken review feedback

- self mode: validate the adopted PAT belongs to spec.forProvider.serviceAccountId
  (PersonalAccessToken.UserID) and surface a terminal error on mismatch, so a
  miswired credentials secret can no longer rotate/revoke the wrong service
  account's token while the reconcile still succeeds.
- owner mode: narrow the rotate->create fallback. Only fall through to a fresh
  create when the existing token is genuinely gone (404, or the specific
  'Token already revoked' 400). Any other error (generic 400, 403, 5xx,
  transport) now returns instead of minting a second token.
- cluster scope: fix self-mode detection for cluster-scoped resources. A
  cluster resource has no namespace and writes to a full SecretReference, so
  isSelfManaged must compare the credential secret namespace against the write
  reference's namespace. Implemented as a generator replacement so the cluster
  zz_ code is regenerated correctly.
- client: filter the service-account token list with state=active to avoid
  paginating through revoked/expired tokens on every Observe poll.
- crd: add the 'saat' shortName for friendlier kubectl usage.

Regenerated cluster-scoped code and CRDs via make generate.

Signed-off-by: Markus Siebert <markus.siebert@deutschebahn.com>

* fix(common): carry CredentialsSecretRef through the legacy ProviderConfig path

Cluster-scoped resources are LegacyManaged and resolve their credentials via
UseLegacyProviderConfig, which built a Config without CredentialsSecretRef. As
a result isSelfManaged() always saw a nil ref and self-managed mode never
activated for cluster-scoped ServiceAccountAccessTokens, even when the
ProviderConfig read from the exact secret the resource writes to (it stayed
SelfManaged=False / OwnerManaged and then 404'd on the owner path).

Populate CredentialsSecretRef from pc.Spec.Credentials.SecretRef in the legacy
path, mirroring the modern namespaced path, so self-mode detection works for
cluster-scoped resources too.

Co-authored fix and test verifying the legacy builder carries the ref.

Signed-off-by: Markus Siebert <markus.siebert@deutschebahn.com>

* style(common): fix gci import grouping in helper_test.go

Move the provider-gitlab-local imports into their own trailing gci group to
satisfy the project's gci section order (standard, default, prefix).

Signed-off-by: Markus Siebert <markus.siebert@deutschebahn.com>

---------

Signed-off-by: Markus Siebert <markus.siebert@deutschebahn.com>

Author: markussiebert

README.md

@@ -44,6 +44,51 @@ spec:
 kubectl apply -f examples/providerconfig/provider.yaml
 ```
 
+### Self-rotating service account tokens
+
+The namespaced `groups.gitlab.m.crossplane.io/v1alpha1` `ServiceAccountAccessToken`
+resource can keep a short-lived token alive by rotating it before it expires.
+
+It supports two modes, selected automatically:
+
+* **Owner mode** (default): the `ProviderConfig` is a group owner. The token is
+  created, observed, rotated and revoked through the group service-account
+  endpoints.
+* **Self-managed mode**: the `ProviderConfig` authenticates with the *very token*
+  this resource manages — i.e. the `ProviderConfig.credentials.secretRef` points
+  at the same secret (namespace, name and `token` key) that the resource writes
+  via `writeConnectionSecretToRef`. The provider then acts as the service account
+  itself and uses the self endpoints (`GET/POST /personal_access_tokens/self`).
+  This lets a short-lived token reconcile a whole group and keep itself alive by
+  self-rotating. A `SelfManaged` status condition reports the active mode.
+
+> **Bootstrap secret type.** In self-managed mode the rotated token is written
+> back into the secret the `ProviderConfig` reads. Crossplane only writes
+> connection secrets it controls, so a **hand-created** bootstrap secret must use
+> the connection secret type `connection.crossplane.io/v1alpha1` — a default
+> `Opaque` secret (e.g. from `kubectl create secret generic`, which has no
+> `--type` flag) is rejected with `refusing to modify uncontrolled secret of type
+> "Opaque"`. Create it from a manifest:
+>
+> ```yaml
+> apiVersion: v1
+> kind: Secret
+> metadata:
+>   name: gitlab-self-rotating-token
+>   namespace: default
+> type: connection.crossplane.io/v1alpha1
+> stringData:
+>   # a service account PAT with at least the `api` and `self_rotate` scopes
+>   token: "<PERSONAL_ACCESS_TOKEN>"
+> ```
+>
+> Alternatively, bootstrap in owner mode first (Crossplane then creates and owns
+> a correctly typed connection secret), and switch `providerConfigRef` to the
+> self `ProviderConfig` afterwards.
+
+See [`examples/groups/serviceaccountaccesstoken.yaml`](examples/groups/serviceaccountaccesstoken.yaml)
+for full examples of both modes.
+
 ## Contributing
 
 provider-gitlab is a community driven project and we welcome contributions. See