GitLab Certificate-Based Kubernetes Integration Sunset on GitLab.com in May — when and how should I migrate?
Migrate GitLab.com deployments off the legacy certificate-based Kubernetes integration before it stops working in May 2026.
Blockers
- capability/certificate-based-kubernetes-integration — EOL 2026-05-31
- GitLab's current replacement for the deprecated certificate-based integration is the GitLab agent for Kubernetes with the CI/CD workflow.
- GitLab documents GitOps as a primary production-ready Kubernetes workflow with the agent-based model.
- GitLab-managed Kubernetes resources use the agent-based security model instead of the deprecated certificate integration.
- GitLab-managed Apps were removed in GitLab 15.0.
Who this is for
- enterprise
- compliance
- microservices
Candidates
Migrate to the GitLab agent for Kubernetes with the CI/CD workflow
GitLab's current replacement for the deprecated certificate-based integration is the GitLab agent for Kubernetes. As of 2026-04-01, GitLab documents the agent-based model for GitLab.com, GitLab Self-Managed, and GitLab Dedicated, and the Kubernetes clusters docs list it under Free, Premium, and Ultimate tiers. The migration guide says this workflow keeps the agent off the public internet and avoids giving GitLab full cluster-admin access. For Auto DevOps, GitLab documents moving to agent-based variables such as KUBE_CONTEXT and KUBE_NAMESPACE, then disabling the old certificate-based cluster entry.
When to choose
Use this when you still deploy from GitLab CI/CD and want the lowest-friction replacement for certificate-based deployments. It is the direct path when your current pipelines already push manifests or charts from GitLab runners.
Tradeoffs
Keeps the existing CI/CD operating model and works across GitLab tiers, but you must update pipeline config and cluster authorization. Legacy cluster-level concepts do not carry over directly, because the agent is configured in a single project and then shared outward.
Cautions
GitLab-managed Apps are not supported by the agent and were removed in GitLab 15.0, so environments still depending on those need a separate migration first. The migration guide also instructs you to turn off the old certificate-based cluster after the agent path is working.
Migrate to the GitOps workflow with the GitLab agent
GitLab documents GitOps as a primary production-ready Kubernetes workflow and recommends the agent-based model over the deprecated certificate integration. As of 2026-04-01, the agent documentation positions GitOps as the recommended workflow for connecting Kubernetes clusters to GitLab. This path removes dependence on the legacy direct certificate connection and shifts deployment authority toward pull-based reconciliation in the cluster. It is the cleaner long-term replacement when you want to standardize cluster access and reduce pipeline-held Kubernetes credentials.
When to choose
Use this when you want a stronger operational boundary, especially for shared clusters, regulated environments, or multi-team platform setups. It is the better fit when you are willing to change deployment mechanics instead of only swapping connection plumbing.
Tradeoffs
Gives a more robust long-term operating model and aligns with GitLab's recommendation, but it is a bigger process change than the CI/CD workflow. Teams need GitOps repo patterns and controller practices, not just a pipeline variable update.
Cautions
The old project-level, group-level, and instance-level cluster model is deprecated; with the agent, sharing is done by exposing one project-scoped agent connection to other projects or groups. Check official docs for the exact GitOps controller and Helm compatibility details for your Kubernetes version.
For legacy GitLab-managed clusters, move to GitLab-managed Kubernetes resources with the agent
GitLab provides a specific migration path for teams that previously relied on GitLab-managed clusters creating namespaces and service accounts automatically. As of 2026-04-01, the migration section for this path is documented for Premium and Ultimate tiers. GitLab-managed Kubernetes resources let teams keep self-service environment resource creation while using the agent-based security model instead of the deprecated certificate integration. This is the targeted replacement when your blocker is not only connectivity, but also the loss of GitLab-created per-environment resources.
When to choose
Use this when the legacy integration was doing namespace-per-environment or similar GitLab-managed resource setup that your teams still depend on. It is the right path if a plain agent migration would otherwise regress environment provisioning behavior.
Tradeoffs
Preserves more of the old operational behavior, but it is more involved than a generic CI/CD migration. It also fits a narrower set of legacy GitLab-managed cluster users.
Cautions
The migration guide requires checking whether Namespace per environment was enabled and then reproducing the legacy namespace pattern in environment templates. If your setup also used GitLab-managed Apps, that must be migrated separately because the agent does not support them.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "GitLab Certificate-Based Kubernetes Integration Sunset on GitLab.com in May — when and how should I migrate?"