Static Control Plane config silently ignores sharedSSOName/userGroups under projects[], and there's no API/CLI/IaC way to set them

Start with ControlPlaneProject in pkg/config/control_plane.go and the SSO login path in pkg/app/server/httpapi/login.go; compare those with the datastore Project model and existing project RPCs in pkg/app/server/service/webservice/service.proto. First determine which proposed fix to pursue, since the issue lists several independent options. Done means static config or a supported API/CLI/IaC path can manage the project SSO and group mappings, with unsupported config handled explicitly.

Summary:
The Control Plane's static YAML config accepts sharedSSOName and userGroups keys under spec.projects[], but ControlPlaneProject (pkg/config/control_plane.go) only defines id, desc, and staticAdmin. These extra keys parse without error and are silently dropped — nothing in the config ever reaches the project's actual datastore record, and no validation warns that they're unsupported. Separately, even if you set a project up correctly via the ops console, there is no scripted/API way to populate userGroups (SSO group → role mappings) — this can currently only be done by clicking through the web console UI after logging in as that project's admin. Together, these make it effectively impossible to manage a PipeCD project (with SSO + RBAC group mappings) as code.

Steps to reproduce

1. Add a project to the Control Plane config with sharedSSOName and userGroups set, e.g.:

apiVersion: pipecd.dev/v1beta1
kind: ControlPlane
spec:
  projects:
    - id: my-project
      staticAdmin:
        username: admin
        passwordHash: "<bcrypt hash>"
      sharedSSOName: gitlab
      userGroups:
        - ssoGroup: my-org/my-team
          role: Admin
  sharedSSOConfigs:
    - name: gitlab
      provider: OIDC
      oidc: {...}

2. Start the Control Plane. Config loads with no error.

3. Log in via static admin for my-project — this succeeds (served from the in-memory projectsInConfig map).

4. Try to log in via SSO for my-project — this fails with: auth-handler: Unable to find project my-project {"error": "not found"} because handleSSOLogin (pkg/app/server/httpapi/login.go) only ever calls projectGetter.Get() against the datastore, with no fallback to projectsInConfig the way handleStaticAdminLogin has.

Root cause (traced in source)

• ControlPlaneProject struct (pkg/config/control_plane.go:53) has only 3 fields: ID, Desc, StaticAdmin. sharedSSOName/userGroups in the YAML have nowhere to deserialize into, so they're silently discarded by the YAML/JSON decoder.

• The real model.Project (datastore record, pkg/model/project.pb.go) does have SharedSsoName and UserGroups fields — but a project only gets a datastore row via the ops console's "Add Project" form (pkg/app/ops/handler/handler.go, handleAddProject), and that form only has 4 fields: ID, Description, SharedSSO, AllowStrayAsViewer. There is no form field, CLI command, or API for userGroups.

• AddProjectUserGroup/DeleteProjectUserGroup do exist as gRPC WebService RPCs (pkg/app/server/service/webservice/service.proto), callable only after SSO or static-admin login — but this is a chicken-and-egg problem for the very first group mapping (you need SSO working to easily reach the UI as a non-static-admin, and SSO won't work until a group mapping exists... though static-admin login can reach the same settings page, so it's workable, just entirely manual).

• pipectl has no project subcommand at all (confirmed against cmd/pipectl/main.go's registered command packages: application, deployment, encrypt, event, migrate, piped, planpreview, plugin, transfer — no project).

• The official terraform-provider-pipecd only implements pipecd_piped and pipecd_application resources — no pipecd_project resource exists to manage SSO config or user groups.

Impact

• Operators following the documented static-config format for sharedSSOName/userGroups will have SSO silently broken with no indication that the config fields they set have no effect.

• There is no way to manage project SSO/RBAC configuration as code (Terraform, a pipectl command, a CI script, etc.) — it is a fully manual, UI-only, per-project, post-creation step.

Suggested fixes (any subset would help)

1. Validation: reject or warn on unrecognized keys under spec.projects[] at config-load time, so sharedSSOName/userGroups typos/misunderstandings fail loudly instead of silently.

2. Docs: clarify in the Control Plane config reference that sharedSSOName and userGroups are datastore-only properties, not static-config properties, and link to how to set them (ops console + web UI).

3. CLI: add a pipectl project command group wrapping the existing AddProjectUserGroup/DeleteProjectUserGroup/UpdateProjectSSOConfig gRPC calls, and ideally a project add wrapping the ops console's project-creation flow too.

4. Terraform provider: add a pipecd_project (or pipecd_project_user_group) resource to terraform-provider-pipecd wrapping the same RPCs, enabling real IaC management of project RBAC.

Environment

• PipeCD version: 0.56.0
• Confirmed the same on master as of 2026-10-26 by reading source directly.