Konstruct 0.6

Released: July 2026

Highlights

• GitLab git provider — onboard with GitLab alongside GitHub; full OAuth flow, Group Access Tokens, and provider-aware operators across the entire platform
• Broadcasts — platform-wide announcements with Markdown content, severity levels, and optional scheduling; managed through a new Admin section and surfaced as a banner to all users
• MCP diagnostics — new API endpoints for inspecting operator pods, CRD definitions, and CR instances so AI assistants can troubleshoot the platform directly
• RBAC overhaul — rank-based authorization model with a single enforcement entrypoint, mode-aware role definitions, and per-org role gating in the UI
• API keys redesign — refreshed list and create flow per the latest design system, global vs. org-scoped keys, and per-bucket activity tracking
• Cluster name validation — real-time availability check as you type in cluster create forms
• Cloud account secret redaction — provider credentials are no longer returned in API responses
• GitOps reliability — hard-reset on reused git clones and fresh clones on deletion prevent stale state from being committed
• UI Guide — step-by-step visual documentation with screenshots and video recordings captured from a live Konstruct environment

GitLab git provider

Konstruct now supports GitLab as a first-class git provider alongside GitHub. You can onboard an organization with either provider from the same getting-started flow.

How it works

1. OAuth — Konstruct redirects to your GitLab instance for authorization, then exchanges the OAuth grant for a GitLab Group Access Token (11-month expiry, api + read_repository + write_repository scopes, access level 40).
2. Platform git config — the Group Access Token is stored in a konstruct-git-config Secret on the control plane; all operators read credentials from this centralized config rather than per-resource secrets.
3. GitOps repository initialization — the gitaccount-operator creates the org's GitOps repository with main as the default branch (matching GitLab's default), and creates a GitLab sub-group as the org namespace.
4. Provider-aware operators — the workloadcluster-operator, team-management-operator, and application-operator all detect the git provider and use the correct authentication and URL parsing for GitLab's nested group paths.

UI onboarding

The git connection page now shows both GitHub App and GitLab OAuth options side by side. After authenticating with GitLab:

• You select the GitLab group to use as the org namespace
• Konstruct mints a GitAccount CR automatically on group selection
• The default pipeline template is shown for the selected provider
• The Repositories page renders both GitOps and app repositories using the group's full path

What's different from GitHub

	GitHub	GitLab
Auth mechanism	GitHub App installation token	Group Access Token via OAuth
Org namespace	GitHub org name	GitLab sub-group
Default branch	main	main
Credential storage	Vault (GitHub App private key)	konstruct-git-config Secret
Repo URL format	github.com/{org}/{repo}	Nested group path gitlab.com/{group}/{subgroup}/{repo}

Broadcasts

A new broadcast system lets Platform Admins push announcements to every user on the platform — maintenance windows, feature launches, incident updates, or policy changes.

Broadcast CRD

The team-management-operator now manages a cluster-scoped Broadcast custom resource (broadcast.konstruct.civo.com):

Field	Description
message	Markdown content rendered with remark-gfm and sanitized with rehype-sanitize
severity	info, success, warning, or critical — controls banner color
active	Boolean toggle; inactive broadcasts are hidden from end users
startAt / endAt	Optional schedule; status is derived at read time, never persisted

The operator manages a revision annotation and an Acknowledged status condition on each Broadcast CR.

REST API

Full CRUD under /api/v1/broadcasts:

• GET /api/v1/broadcasts — list all broadcasts (all authenticated users)
• POST /api/v1/broadcasts — create a broadcast (Super Admin / Platform Admin)
• GET /api/v1/broadcasts/{name} — get a single broadcast
• PUT /api/v1/broadcasts/{name} — update a broadcast
• DELETE /api/v1/broadcasts/{name} — delete a broadcast

Write operations record createdBy and updatedBy from the caller's JWT identity.

Admin UI

The Broadcasts section in the sidebar opens an admin page where Platform Admins can:

• Create broadcasts with a Markdown editor and severity picker
• Set optional start/end dates for scheduled broadcasts
• Edit or delete existing broadcasts

End users see active broadcasts as a colored banner at the top of every page. Severity maps to color: info (blue), success (green), warning (amber), critical (red).

MCP diagnostics

New API endpoints give AI assistants (connected via the Konstruct MCP server) the ability to inspect platform internals for troubleshooting:

Endpoint	Description
GET /api/v1/konstruct-pods	List operator pods in the konstruct-system namespace (filtered by control-plane=controller-manager)
GET /api/v1/konstruct-pods/{name}/logs	Fetch logs from a specific operator pod
GET /api/v1/konstruct-crds	List all Konstruct CRDs (scoped to *.konstruct.civo.com)
GET /api/v1/konstruct-crds/{name}	Get CRD details (schema, versions, scope)
GET /api/v1/konstruct-crds/{name}/instances	List CR instances for a CRD
GET /api/v1/konstruct-crds/{name}/instances/{namespace}/{instanceName}	Get a specific CR instance

Sensitive fields are scrubbed from CR instance responses. The operator namespace and label selector are configurable via KONSTRUCT_OPERATOR_NAMESPACE and KONSTRUCT_OPERATOR_LABEL_SELECTOR environment variables.

RBAC overhaul

The 0.6 release consolidates and tightens the authorization model across the API and UI.

API changes

• Single enforcement entrypoint — four separate authorization helpers are replaced by EnforceNamespaceRole, which takes a minimum role rank and the target namespace. Rank-based comparison replaces string matching throughout.
• Role behavior by rank:

Role	Permissions
Developer	Create/edit environments, manage full catalog deployment lifecycle, read-only on clusters and templates
Team Admin	Full template lifecycle (create/update/delete), manage cloud and git accounts on SaaS, no cross-org access
Platform Admin	Cluster-wide override equivalent to Super Admin (IsGlobalAdmin)

• Team management mutations are restricted to Super Admin and Platform Admin only.
• Mode-aware /roles endpoint — GET /roles and GET /roles/{role_name} now return different permission matrices for SaaS vs. self-hosted deployments. On SaaS, Team Admins see cloud and git account read/write in their role matrix; delete stays Platform Admin only.
• API key identity — /roles/user now returns the caller's OrgRoles directly. API key creation snapshots the issuer's Groups onto the Secret so downstream authorization works correctly.
• List endpoint filtering — unscoped list endpoints use minimum-rank filtering. Platform Admins no longer bypass into orgs they don't belong to via list endpoints.

UI changes

• Per-org role gating — the UI reads the orgRoles JWT claim and gates actions per organization, not just by global role.
• Global 403 toast — all permission errors surface a friendly toast via a pub/sub bus instead of failing silently or showing raw error text.

API keys redesign

The API keys page has been redesigned to match the latest Figma spec (3368-30375):

• Refreshed list — updated to @konstructio/ui v0.1.2-alpha.95 with the latest design system components
• Global keys — when viewing All organizations, you can create a key that works across every org. The list shows a Global vs. org-scoped pill in the Available to column.
• Discriminated create flow — the CreateAPIKeyRequest is now a discriminated union; global keys omit the role field since they inherit the issuer's full permissions.
• Per-bucket activity counting — the list shows active key counts grouped by type.

Cluster name validation

A new GET /api/v1/team-management/{name}/clusters/validate endpoint checks whether a cluster name is available before you submit the create form:

• Management cluster names must be globally unique
• Workload cluster names are scoped to the organization
• Names are validated against RFC 1123 format

The UI calls this endpoint as you type in the cluster name field and shows inline feedback — a green check for available names, a red error with the reason for unavailable or invalid names. The submit button is gated until the name passes validation.

Cloud account secret redaction

Provider credentials (API tokens, secret keys, access keys) are no longer included in GET /cloud-account API responses. This is a defense-in-depth measure against accidental credential exposure through API responses, logs, or browser dev tools. Credentials are still stored and used internally by the operators.

GitOps reliability

Two fixes prevent stale git state from causing incorrect commits during operator reconciliation:

• Hard-reset on reused clones — the workloadcluster-operator now runs a hard reset to origin before writing to a reused git clone, preventing stale files from prior reconciles from being committed alongside new changes.
• Fresh clone on deletion — the team-management-operator forces a fresh clone when deleting cluster resources, preventing stale state from interfering with cleanup.

Additional operator improvements:

• PVC sizing — operator workspace PVCs increased from default to 50Gi across all operators to prevent git clone failures on large GitOps repositories
• Konstruct-templates version — the team-management-operator reads the konstruct-templates catalog version from a KONSTRUCT_VERSION environment variable instead of hardcoding it
• Workload cluster template auto-creation — the team-management-operator auto-creates a default WorkloadCluster cluster template when provisioning a new organization

CatalogDeployment and environment deletion improvements

CatalogDeployment finalizer

Deleting a catalog deployment now runs a two-phase cleanup:

1. YAML removal — Konstruct removes the deployment's configuration from the project GitOps repository
2. Argo CD drain — Konstruct waits for Argo CD to prune the in-cluster Applications before removing the IaC directories, requeuing every 10 seconds during the pruning phase

ApplicationDeployment finalizer

Application deployments now have their own finalizer that removes GitOps configuration on deletion.

Environment finalizer improvements

The environment finalizer now scrubs all WorkloadCluster Spec.Environments entries for the deleted environment across every cluster in the namespace, ensuring no cluster references a removed environment.

Structured environment fields

CatalogDeployment.Spec.Env and WorkloadCluster.Spec.Env now use typed {Name, Namespace} pairs alongside the legacy environments string arrays. Finalizers clean both legacy and new-format paths.

UI Guide and E2E documentation

A new UI Guide section provides step-by-step visual documentation with screenshots and video recordings captured from a live SaaS instance. Every core workflow has been verified by a 37-spec Cypress end-to-end test suite covering:

• Organizations
• Clusters (management and workload)
• GitOps catalog
• App repositories
• Environments
• Git providers
• Cloud accounts
• SSO configuration
• Team management
• API keys

Screenshots are captured at 1920x1080 in headless Chrome with human-paced timing for clear, readable results.

Breaking changes

None for end users. Existing resources continue to work as-is.

Direct API consumers should note:

• The new diagnostics endpoints (/konstruct-pods, /konstruct-crds) require the konstruct-api ServiceAccount to have RBAC access to read CRDs and pods in the operator namespace. The Helm chart includes these permissions automatically.
• Cloud account API responses no longer include provider credentials. If you were reading credentials from API responses, retrieve them from your cloud provider directly.

Upgrade notes

To upgrade, update the targetRevision in your platform team's topmost GitOps repository (the Argo CD Application manifest for Konstruct) to 0.6.0:

spec:
  source:
    chart: konstruct
    repoURL: oci://europe-west2-docker.pkg.dev/civo-com/charts
    targetRevision: 0.6.0

Commit and push — Argo CD syncs the new version automatically. No manual migration steps are required.

Additional notes:

• The Broadcast CRD and associated RBAC are included in the Helm chart automatically.
• GitLab support requires configuring the GitLab OAuth application and setting the konstruct-git-config Secret with your GitLab instance URL and credentials.
• All operator module paths have been migrated to civo/konstruct/*. This is transparent for Helm-based installations.

What's next?

• UI Guide — visual walkthrough of every Konstruct workflow
• API keys — generate API and MCP keys
• GitOps catalog — deploy and manage catalog items
• Cluster templates — create and share templates across orgs
• Environments — namespace-aware environments