Operator reference
Reason codes
Every code the operator puts on a condition, an Event or an admission denial.
Every condition, Event and admission denial the operator writes carries one
of these codes, never free text: alerts, scripts and kubectl filters can
rely on them. The list is generated from the operator's source, so it
matches the installed version.
- Blocking:
ReadyturnsFalsewith this reason, and every failed reconcile records aWarningEvent with it (Events). An admission webhook denial carries one too (HTTP 403, the code as its reason). - Advisory: the CR still works.
Reconciledis the reason ofReady: True; the others are a condition of their own (itstypeis the code, itsstatus"True") or a lifecycle Event.
Every CR's Ready reason also labels the reconcile counter
(Metrics & health), so a code can be graphed and
alerted on. To find where one shows up right now:
kubectl get events -A --field-selector reason=InstanceNotFound| Code | Severity | Shows as | Meaning | What to do |
|---|---|---|---|---|
Reconciled | advisory | Ready: True | Generic success reason for Ready: True — every condition must carry a ReasonCode, so this is the one every reconciler uses on the happy path rather than each inventing its own "it worked" code. | Nothing |
InstanceNotFound | blocking | Ready: False, Event (Warning) | spec.instanceRef does not resolve to a ForgejoInstance nor a ForgejoLocalInstance the operator sees (or can't be satisfied as written), or no instanceRef was given and there is no instance to default to. | Create the instance, or fix instanceRef |
AmbiguousDefaultInstance | blocking | Ready: False, Event (Warning) | No instanceRef was given and there is more than one instance to choose from. | Set instanceRef |
InstanceNotAllowed | blocking | Ready: False, Event (Warning) | The instance named is out of reach: a ForgejoLocalInstance of another namespace that doesn't share itself with this one, or outside the namespace the operator is limited to. | Use an instance of the CR's namespace, or have that ForgejoLocalInstance list it in sharedWith |
InstanceBindingChanged | blocking | Ready: False, Event (Warning) | spec.instanceRef now designates another instance than the one recorded in status.instance: a bound CR never moves — the ids in its status belong to the instance they were created on. Nothing is done until instanceRef designates it again. | Set instanceRef.kind to the instance you want (see A namespace's own instance) |
InstanceUnreachable | blocking | Ready: False, Event (Warning) | The Forgejo API could not be reached (DNS, TCP, TLS) or answered with a 5xx. | Timeouts and rate limiting (408/429) land here too. Check Forgejo's health and the URL/CA; it's retried automatically |
TokenSecretNotFound | blocking | Ready: False, Event (Warning) | The ForgejoInstance token Secret (or the key in it) is missing. | Fix tokenSecretRef or create the Secret |
InstanceTokenNotAdmin | blocking | Ready: False, Event (Warning) | The ForgejoInstance token doesn't belong to a Forgejo site admin: the admin APIs the operator relies on would fail on every CR. Use a site admin's token. | |
TokenSecretNotAllowed | blocking | Ready: False, Event (Warning) | The token Secret of a ForgejoLocalInstance doesn't carry the forgejo.weebo.io/instance-token: "true" label. The operator reads Secrets with its own rights: a local instance may only use a Secret its namespace labelled for it. Label the Secret. | |
SecretNotAllowed | blocking | Ready: False, Event (Warning) | A Secret a CR hands to Forgejo as a credential (migrate.authSecretRef, a webhook's secretRef or authorizationHeaderSecretRef) doesn't carry the forgejo.weebo.io/credential: "true" label. Label the Secret. | |
Bound | advisory | Event (Normal) | This CR is now bound to a Forgejo object — created, adopted by the importer, or observed (Event only: status.forgejoId was just recorded). | Nothing |
Released | advisory | Event (Normal) | The finalizer finished: the Forgejo object was deleted or kept per deletionPolicy/managementPolicy (or force-orphaned), the emitted secrets removed (Event only). | Nothing |
InstanceInUse | blocking | Ready: False, Event (Warning) | A ForgejoInstance can't be deleted while CRs still use it. | Delete the CRs bound to the instance first |
KubernetesApiError | blocking | Ready: False, Event (Warning) | A Kubernetes API call made while resolving the ForgejoInstance (listing instances, reading its token or CA Secret) failed. Usually transient (apiserver hiccup); retried like any error. | Transient; retried automatically |
ForgejoObjectAlreadyExists | blocking | Ready: False, Event (Warning) | Create was rejected because an object with the same name already exists in Forgejo and isn't tracked by this CR. Never adopted implicitly — only the importer binds a CR to an existing object. | For a webhook (same URL) or an OAuth2 application (same name), it can be a twin left by a lost create response. Rename the CR's spec.name, delete the twin, or adopt the object with the importer |
ForgejoApiError | blocking | Ready: False, Event (Warning) | Catch-all for a Forgejo API call that failed for a reason not covered by a more specific code. | Read the message; often a missing token scope |
ReferenceNotFound | blocking | Ready: False, Event (Warning) | A *Ref field does not resolve to a CR (or its remoteName to an object of the instance). | Create it or fix the ref |
ReferenceNotAllowed | blocking | Ready: False, Event (Warning) | A *Ref field names a CR of another namespace while the operator doesn't allow cross-namespace references (references.crossNamespace), or the target doesn't list this namespace in its sharedWith. | Reference a CR of this namespace; or enable references.crossNamespace on the release and list this namespace in the target's sharedWith |
RemoteObjectClaimed | blocking | Ready: False, Event (Warning) | The Forgejo object this CR would create or adopt (same server, kind and name) is already owned by another CR, possibly in another namespace or through another instance of the same server. Nothing is called; reference it with remoteName instead, or rename it. For an access token: another CR already issues a token of that name for the same user. | Another CR owns that Forgejo object: reference it with remoteName, or rename this one |
ReferenceNotReady | blocking | Ready: False, Event (Warning) | A *Ref field resolves to a CR that isn't Ready yet (no status.forgejoId). The controller watches the referenced kind, so this clears as soon as the reference becomes ready. | Fix that CR first; this one follows on its own |
UserNotFound | blocking | Ready: False, Event (Warning) | A ForgejoUser in managementPolicy: Observe does not exist in Forgejo yet — typically an OIDC user who hasn't logged in once. | Wait for their first sign-in |
MemberPending | advisory | condition MemberPending: True, Event (Normal) | A ForgejoTeam member is a ForgejoUser that doesn't exist in Forgejo yet; the other members are still synced. Advisory. | Wait for those users' first sign-in; the other members are synced |
LoginSourceNotFound | blocking | Ready: False, Event (Warning) | ForgejoUser.spec.loginSource doesn't match any authentication source configured in Forgejo. | Fix the id (Site administration → Authentication sources) |
UnsupportedForgejoVersion | blocking | Ready: False, Event (Warning) | The ForgejoInstance runs a Forgejo older than v16 — the admin token API this operator relies on is missing. | Upgrade Forgejo |
DisruptiveUpdateRefused | blocking | Ready: False, Event (Warning) | The change requires a delete-and-recreate (repository transfer, token scope change, OAuth2 owner change) and the CR lacks the forgejo.weebo.io/allow-disruptive-update: "true" annotation. | See Disruptive changes |
NamespaceNotAllowed | blocking | Ready: False, Event (Warning), admission denial | Refused by ForgejoNamespacePolicy (webhook and/or reconciler). | Adjust the allow-list; a site admin's credentials need an explicit rule |
CrossNamespaceReference | blocking | Ready: False, Event (Warning) | A namespaced CR references a namespaced CR in another namespace. | Typically a secretTargets entry in another namespace: write into the CR's own namespace |
SecretTargetFailed | blocking | Ready: False, Event (Warning), admission denial | A SecretStore (Kubernetes or Vault) write/delete/auth call failed, or a Vault target's explicit path is outside <pathPrefix>/<namespace>/ and no pathGrants entry of the instance opens it (also refused at admission). | Check RBAC or Vault access and the target's namespace/path (a Vault path outside <pathPrefix>/<namespace>/ needs a pathGrants entry on the instance) |
InvalidSpec | blocking | Ready: False, Event (Warning) | The spec is schema-valid but not a shape a reconciler can act on (e.g. a one-of discriminator without its matching sub-struct). | Fix the spec (e.g. not both organizationRef and userRef); the message says what's wrong |
InvalidVaultPathGrants | blocking | Ready: False, Event (Warning) | The ForgejoInstance's secretStore.vault.pathGrants holds an invalid grant (no namespace and not clusterScoped, or both; a path pattern with an empty, . or .. segment, a * before its last segment, or no literal segment). Vault targets fail until it is fixed. | Fix secretStore.vault.pathGrants on the instance; the message names the entry |
LeavesWatchScope | blocking | Ready: False, Event (Warning) | An update would take a CR still carrying the finalizer out of the operator's label selector (watch.labelSelector): refused at admission. | Set the force-orphan annotation first, or move the CR to another release's selector and remove its finalizer |