To upgrade a self-hosted GitLab Duo AI Gateway safely, match the Gateway image to your GitLab version, preserve the deployment’s configuration and secrets, update the image using the procedure for your deployment method, then verify readiness and test the Duo features you use. Treat a Gateway image refresh separately from a GitLab application or chart upgrade: the latter has its own backup, version-mapping, and sequencing requirements.
Before you upgrade: identify what is changing
Record the GitLab version, current AI Gateway image tag and digest, deployment method, and (for Kubernetes) the installed chart version. Save the current container or Helm configuration, including environment variables, secrets, TLS and ingress settings, and image pull policy. Keep signing and validation keys and other required credentials secure.
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
Self-Hosted Stack: Mini PCs, Cloudflare | $10.00 | Buy on Amazon |
Decide whether this is only a Gateway image refresh, a Gateway Helm chart update, or a combined GitLab application upgrade. A Gateway image change alone does not perform a GitLab chart upgrade or its migrations.
Choose a compatible AI Gateway image
GitLab’s documented convention is to use the latest available stable AI Gateway image tag in the matching self-hosted-vX.Y.*-ee line when GitLab is on vX.Y.*-ee. Check the registry for the actual tag; do not assume an unversioned latest tag exists or is appropriate. For example, GitLab’s installation documentation uses self-hosted-v18.2.2-ee for GitLab v18.2.1-ee when that is the latest listed tag. Stable releases with explicit version tags are preferred; nightly builds do not guarantee backward compatibility. See GitLab’s AI Gateway installation instructions.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
For repeatable deployments, consider pinning the exact image digest as well as recording the tag. In Kubernetes, check the chart version separately from the Gateway image tag. The chart’s version numbering is not a substitute for matching the Gateway image to the GitLab version.
Upgrade a Docker deployment
- Capture the existing run configuration. Record the current image reference, environment variables, network settings, TLS-related configuration, and securely stored secrets. Ensure you can recreate the existing container if the new one does not work.
- Pull the selected stable image. GitLab’s documented instruction is to download the newest Docker image tag. Verify the image digest before and after pulling if you need to confirm which image is present.
- Replace the container. Stop and remove the existing container, then run the new image with the required configuration carried forward. Avoid dropping required keys, credentials, or endpoint settings when recreating it.
- Check service health and feature behavior. Confirm the Gateway starts and can reach the configured GitLab endpoint, then test the Duo features that depend on it.
Use the Docker procedure in the official installation documentation alongside the run configuration used by your deployment.
Upgrade a Kubernetes or Helm deployment
- Review the installed chart and values. Record the chart version and the current values, image reference, pull policy, secrets, TLS, ingress, and endpoint configuration. Preserve any deployment-specific overrides.
- Set the intended Gateway image. Use a compatible stable tag or digest, and verify chart-specific prerequisites for the deployment path you use. The standalone AI Gateway Helm chart is documented as experimental; it was introduced in GitLab 19.1 and its documented prerequisites and configuration vary by version. GitLab 19.2 adds guidance for TLS cipher suites and external runner access. Consult the AI Gateway chart documentation rather than assuming every self-hosted installation uses this chart.
- Check image pull behavior. Chart versions before 0.7.0 use
imagePullPolicy: IfNotPresentby default, which can leave a changed image under the same tag unpulled. Depending on the installed chart, documented options include pinning by digest, settingimage.pullPolicy=Always, or restarting the deployment to force a pull. Check the actual version and values in your release before choosing. - Apply the chart update and watch readiness. Update the Helm release with the intended values, then inspect rollout status and wait for Gateway pods to become Ready before testing requests.
For the standalone chart’s current settings and prerequisites, use the GitLab AI Gateway chart guide. Do not conflate a Gateway release update with upgrading the broader GitLab Helm chart.
For a combined GitLab and Gateway upgrade
If GitLab itself is changing, consult the release-specific upgrade notes and chart version mapping, take a backup, and follow GitLab’s supported upgrade sequence. GitLab’s general Helm chart guidance for zero downtime assumes a multi-node deployment with multiple Webservice and Sidekiq replicas and advances one minor release at a time; these are not requirements for every standalone Gateway image refresh. Follow the applicable instructions in GitLab’s Helm chart upgrade guide.
Free tools Windows power users keep installed
One-click scans. No signup required.
Validate the upgrade, including model inference
- Confirm Gateway health and that the Gateway can reach the configured GitLab endpoint from inside its container or pod. Check the GitLab URL and API URL settings if authentication or requests fail; see GitLab’s self-hosted model troubleshooting guidance.
- Select the self-hosted model for each relevant Duo feature and exercise the feature with a real request.
- Run the GitLab Duo health check, but do not treat it as proof of model inference: it validates connectivity and license status, not inference for Chat or Code Suggestions. Test those features separately.
- In an offline deployment, transfer the updated Gateway container image and check whether the target version also requires a changed executor image tag. Model weights do not need updating solely because GitLab is upgraded; update them when changing models. Follow GitLab’s offline deployment guidance.
Check version-specific upgrade notes
GitLab 19.2.0 endpoint settings
GitLab’s 19 upgrade notes say a direct upgrade to GitLab 19.2.0 can clear the Local AI Gateway URL and Local URL for the GitLab Duo Agent Platform service. The affected settings are under Admin > GitLab Duo > Configuration > Service endpoints. The notes say the issue does not occur on 19.2.1 or later. If a combined upgrade leaves those settings blank, restore and save the endpoint URLs. This is a GitLab application upgrade issue, not a general effect of replacing the Gateway image. See GitLab 19 upgrade notes.
AI Gateway security releases
In a security notice dated February 6, 2026, GitLab said AI Gateway versions 18.6.2, 18.7.1, and 18.8.1 include a critical fix for CVE-2026-1868 and recommended that affected self-hosted deployments upgrade immediately. The notice says exploitation requires authenticated access. Because security guidance and compatible tags can change, check the current notice and installation instructions before selecting a target: GitLab AI Gateway critical patch release and AI Gateway installation documentation.
Plan rollback before replacing the running version
There is no single rollback procedure that applies to every Gateway deployment. Before upgrading, retain the previous image tag or digest, the configuration and secrets needed to run it, and (for Helm) the release history and values. Decide how you will restore the prior deployment and test that procedure where practical. If GitLab itself is upgraded at the same time, reverting only the Gateway image may not reverse changes to other components; use the release-specific GitLab guidance for that situation.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
