Migrate an existing Forgejo

If your Forgejo already has users, organizations and repositories, the operator won't touch them on its own. A CR whose name is already taken in Forgejo stays Ready: False with reason ForgejoObjectAlreadyExists, so the operator never takes over an object by accident.

To bring existing objects under management, use weebo-forgejo-importer. It reads the live instance and creates the matching CRs with each Forgejo id already recorded in their status. The operator then manages that exact object instead of trying to create a new one.

Before you beginCopy Anchor Link

• The operator is installed and a ForgejoInstance is connected.
• A site-administrator token for the importer (read access is enough).
• For --apply, a kube context allowed to create the CRs and patch their status: cluster-admin, or the least-privilege role below.
• If a ForgejoNamespacePolicy exists, the import namespace must be allowed for the imported organizations.

What gets importedCopy Anchor Link

Not imported: OAuth2 applications and access tokens. Forgejo never returns their secrets, so the operator could never hand them out. Recreate them as new CRs (Credentials).

Every imported CR gets deletionPolicy: Orphan: these objects existed before the operator, and deleting a manifest must not destroy them. Switch a CR to Delete once you want that.

Run the importerCopy Anchor Link

The importer ships in the operator image. Run it from a workstation with your kubeconfig mounted. A small shell function keeps the commands below short (use podman instead of docker if that's what you have):

export FORGEJO_TOKEN=<site-admin-token>

importer() {
  docker run --rm -e FORGEJO_TOKEN \
    -v "$HOME/.kube/config:/kubeconfig:ro" -e KUBECONFIG=/kubeconfig \
    --entrypoint /usr/local/bin/weebo-forgejo-importer \
    ghcr.io/batleforc/weebo-forgejo-operator:<version> "$@"
}

Warnings, such as a team member that isn't a known user or a team left out of a repository's teamRefs, are printed to stderr.

Adopt safely: review, apply, then commitCopy Anchor Link

status is a subresource: kubectl apply and GitOps tools never write it. That's why the adoption happens in the cluster, once, before the manifests go to Git.

importer --url https://git.example.com --namespace forgejo --owner weebo > forgejo.yaml

importer --url https://git.example.com --namespace forgejo --owner weebo --apply

kubectl get fjorg,fjteam,fjuser
kubectl -n forgejo get fjrepo,fjhook,fjdkey

Importer RBACCopy Anchor Link

Without --apply the importer never talks to the cluster. With it, it reads the existing CRs (to keep names stable), creates the new ones by server-side apply, seeds their status and removes the pause annotation. It never reads or writes Secrets. A dedicated identity needs no more than:

# Every imported kind is namespaced: bound only in the import namespace
# (--namespace).
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: weebo-forgejo-importer-namespaced
rules:
  - apiGroups: ["forgejo.weebo.io"]
    resources: [forgejousers, forgejoorganizations, forgejoteams,
                forgejorepositories, forgejowebhooks, forgejodeploykeys]
    verbs: ["get", "list", "create", "patch"]
  - apiGroups: ["forgejo.weebo.io"]
    resources: [forgejousers/status, forgejoorganizations/status, forgejoteams/status,
                forgejorepositories/status, forgejowebhooks/status, forgejodeploykeys/status]
    verbs: ["patch"]
---
# The unique-claim check reads the CRs of every namespace and the
# instances' URLs.
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: weebo-forgejo-importer-claims
rules:
  - apiGroups: ["forgejo.weebo.io"]
    resources: [forgejousers, forgejoorganizations, forgejoteams,
                forgejoinstances, forgejolocalinstances]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: weebo-forgejo-importer-claims
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: weebo-forgejo-importer-claims
subjects:
  - kind: ServiceAccount        # or the User/Group running the importer
    name: weebo-forgejo-importer
    namespace: forgejo
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: weebo-forgejo-importer
  namespace: forgejo            # the --namespace you import into
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: weebo-forgejo-importer-namespaced
subjects:
  - kind: ServiceAccount
    name: weebo-forgejo-importer
    namespace: forgejo

Patching status is what lets it adopt an object: keep this role off anyone who shouldn't be able to point a CR at an arbitrary Forgejo object, and remove the binding once the migration is done. The CRs still go through the admission webhook, so the allow-list applies to the import namespace. A user, organization or team another CR already owns on the same server isn't adopted twice (RemoteObjectClaimed).

Finish by handCopy Anchor Link

• Users are imported as Observe: they're never modified, only looked up, so teams and repositories can reference them.
  • With --manage-users they become Manage. A local account is then marked bot: true, because its password can't be known, and the operator never resets it, whatever later changes to the CR: only a password the operator handed out itself (status.passwordEmitted) is ever replaced.
  • A site admin imported with --manage-users keeps admin: true, which needs an Allow rule naming it in allowedUsers for the ForgejoUser kind and the import namespace, even without any policy (see Security model). Without one, its CR is refused.
  • Turning such a user into a regular local user (bot: false plus secretTargets) resets its password into the targets.
• Webhook secrets are write-only in Forgejo. An imported hook keeps its current secret, and edits leave it alone. Adding a secretRef recreates the hook with that secret, which loses its delivery history.
• Organization owners (ownerRef) only matter at creation, so they're left unset.

From cluster-scoped users, organizations and teamsCopy Anchor Link

Releases before the namespaced identities had ForgejoUser, ForgejoOrganization, ForgejoTeam and ForgejoUserKey cluster-scoped. A CRD's scope can't change in place: its CRD — and with it every CR of the kind — must be deleted. weebo-forgejo-operator migrate-to-namespaced moves them without touching Forgejo:

ForgejoUser/alice: team-a
ForgejoOrganization/weebo: platform

weebo-forgejo-operator migrate-to-namespaced --dry-run \
  --mapping mapping.yaml --default-namespace platform --out ./migration

Vault values keep their old owner id (the tool can't reach Vault): each moved ForgejoUser/ForgejoUserKey carries it in its forgejo.weebo.io/previous-owner annotation, and the operator takes those values back, recording its new id on its next write. Remove the annotation once every value is rewritten.

One thing the tool can't do for you: a user that wrote into another namespace than the one it moves to is refused (CrossNamespaceReference) until its secretTargets follow it (the dry run warns).

NextCopy Anchor Link

Hand out credentials for the imported repositories: Credentials.