• English

      • External Component Compatibility Matrix

      Last updated: 2026-07-01.

      This page is based on the external APIs the platform actually calls. Use it before installation, upgrades, or troubleshooting to choose a practical version range. “Supported range” is what the current implementation prioritizes for validation, while “Recommended version” is the safer choice for a new deployment. For SaaS products such as GitHub.com and Docker Hub, the current public API is the compatibility boundary because there is no installable server version.

      Compatibility overview

      External componentInterface or capability usedSupported rangeRecommended versionNotes
      GitHub.com / GitHub Enterprise ServerREST API, OAuth App, Webhooks, repository/branch/content reads; requests send X-GitHub-Api-Version: 2022-11-28Current GitHub.com; GHES 3.17 ~ 3.21 as of the 2026-07-01 support windowGitHub.com or GHES >= 3.18Older GHES versions may still expose the endpoints but be out of security support. GHES 3.17 closes down on 2026-08-25. Validate OAuth callback, webhook creation, /user/repos, and contents API after upgrades.
      Gitea/api/v1 REST API, OAuth2, repository search, branches, contents, repository webhooks1.20.x ~ 1.25.x1.25.x or current stableGitea's REST API is released with the instance. Check the instance Swagger/OpenAPI page before connecting older private deployments.
      GitLabModel enum only; provider is not implementedNot supportedNot applicableDo not present GitLab as available yet. Add a separate GitLab REST API v4 compatibility entry when implementing it.
      Docker HubDocker Hub API v2 repository search and tag listingCurrent Docker Hub public API v2Current Docker Hub SaaSDocker Hub is SaaS and has no installable version range. Watch for rate limits and network reachability.
      HarborHarbor /api/v2.0/search, /api/v2.0/projects/{project}/repositories/{repo}/artifacts, with Distribution API fallback>= 2.0, validate primarily with 2.10.x ~ 2.14.x2.14.x or current maintained releaseHarbor 2.x keeps the /api/v2.0 path. Keep Basic/Auth Token compatibility in smoke tests.
      Generic OCI/Docker RegistryDocker Registry HTTP API V2: /v2/, /_catalog, /tags/listDistribution API V2 compatible or OCI Distribution Spec 1.0 ~ 1.1Registry that passes OCI Distribution Spec 1.1 compatibilityThe platform only depends on basic catalog/tag APIs. Some registries disable catalog listing; manual image input still works.
      Kubernetes / K3score/v1, apps/v1, batch/v1, networking.k8s.io/v1, Pod logs/exec/events, dynamic clientOfficial support follows client-go v0.36.x: Kubernetes 1.34 ~ 1.36; lower versions are not guaranteedKubernetes/K3s 1.34 ~ 1.36The code uses k8s.io/client-go v0.36.2. For K3s, map the K3s release to its embedded Kubernetes minor version.
      Metrics Servermetrics.k8s.io/v1beta1 Pod metricsMetrics Server compatible with the Kubernetes versionDistribution-recommended Metrics Server versionMissing metrics degrade live resource metrics only; build and release flows still work.
      Kubernetes Gateway APIgateway.networking.k8s.io/v1 GatewayClass, Gateway, HTTPRoute, HTTPRoute filtersGateway API 1.0.0 ~ 1.6.xv1.6.x CRDs, close to the code dependencyThe code depends on sigs.k8s.io/gateway-api v1.6.0; Ingress is no longer the main access route path.
      Traefik Gateway API ProviderKubernetes Gateway provider and Gateway/HTTPRoute reconciliationTraefik 3.xLatest stable Traefik 3.xEnable providers.kubernetesGateway and install Gateway API CRDs. Traefik v2 Gateway API support is not a current target.
      cert-managercert-manager.io/v1 Certificatecert-manager >= 1.0; choose a release supported by the current Kubernetes versionCurrent maintained cert-manager releaseRuntime clusters support manual TLS Secret certificateRefs; HTTP Challenge and DNS-01 wildcard modes can create Certificates and attach their Secrets to the Gateway HTTPS listener. DNS provider credentials and solvers are owned by the Issuer/ClusterIssuer.
      OpenID Connect ProviderOIDC Core 1.0, Discovery 1.0, OAuth2 Authorization Code, ID Token verificationProvider supporting OIDC Core 1.0 + Discovery 1.0Standard implementations such as Logto, Keycloak, Auth0, or GHES OIDCThe issuer must be reachable by the API service. The callback URL must match the one shown by the platform.
      PostgreSQLPostgreSQL wire protocol, GORM, golang-migratePostgreSQL 14 ~ 1817, matching compose/Helm defaultsSQLite is not supported. Production deployments should configure backups and connection limits.
      RedisSingle Redis endpoint, go-redis, Asynq queuesRedis 7.x ~ 8.x8, matching compose/Helm defaultsThe current configuration model uses one Redis address. Redis Cluster/Sentinel are not first-phase targets.
      BuildKitmoby/buildkit:*rootless, buildctl-daemonless.sh, dockerfile.v0 frontendPrimarily validated with v0.24.x-rootless; replacing with v0.20+ rootless requires smoke testsmoby/buildkit:v0.24.0-rootlessBuild Jobs use rootless BuildKit and do not mount the host Docker socket.
      PrometheusPrometheus text exposition format, scraping API/Worker independent /metrics listenersPrometheus 2.40+ or 3.xCurrent stableThe platform exposes metrics but does not use Prometheus as business state.
      GrafanaDashboard JSON and operations iframe URLGrafana 9.x ~ 12.xCurrent stableiframe embedding requires Grafana-side allow_embedding and proper authentication / origin policy handling.
      SMTPSMTP/STARTTLS notification sendingStandard SMTP serviceEnterprise mail, cloud SMTP, or current stable self-hosted SMTPSMTP is a notification adapter. Credentials must be stored as secrets.
      Generic webhook notificationCustom method, URL, and JSON body templatesHTTP/HTTPS endpointCurrent webhook API of the target platformFeishu and WeCom bots can be created as webhook template snapshots. Signing and rate limits belong to the adapter or user configuration.

      Key interface notes

      Git platforms

      The current Git provider implementation supports GitHub and Gitea only. GitHub uses REST API version 2022-11-28; GitHub Enterprise Server should stay within the official support window and include the same REST API behavior. Gitea uses the instance /api/v1, so private Gitea upgrades should rerun repository list, OAuth, webhook creation, and file read smoke tests.

      GitLab is currently only a model enum, not an available provider. Implementing it later should add a separate compatibility entry for GitLab REST API v4, OAuth, and webhooks.

      Registries

      Registries are handled in three groups:

      • Docker Hub uses Docker Hub API v2 and is validated against the current SaaS API.
      • Harbor uses Harbor /api/v2.0 for project/repository search and artifact/tag reads.
      • Other registries use Docker Registry HTTP API V2 or OCI Distribution Spec basics.

      If a registry disables catalog listing, users can still manually enter the image repository and tag. Search and tag suggestions degrade gracefully.

      Kubernetes and Gateway

      Runtime cluster support follows the client-go v0.36.x official compatibility window: Kubernetes 1.34 ~ 1.36. For K3s, use the embedded Kubernetes minor version rather than only the K3s release number.

      Access routes now use Gateway API HTTPRoute as the main path. Clusters must install Gateway API CRDs and run a Gateway API capable controller. The current validation target is Traefik 3.x with its Kubernetes Gateway provider, while the platform model remains generic Gateway API instead of Traefik-specific annotations.

      Database, queue, and builds

      Compose and Helm defaults use postgres:17-alpine and redis:8-alpine. When using managed external services, prefer the same major versions or a documented backward-compatible version. The default build executor is moby/buildkit:v0.24.0-rootless; if replacing it, validate Git clone, Dockerfile frontend, registry login, push, cache import/export, and log collection.

      Upgrade smoke tests

      After upgrading an external component, run at least these smoke tests. A successful connection check alone is not enough:

      1. GitHub/Gitea: OAuth login, repository list, branch list, Dockerfile read, webhook create or reconfigure.
      2. Registry: connection test, repository search, tag listing, build push, runtime image pull.
      3. Kubernetes/K3s: cluster connection test, build Job creation, Deployment/Service creation, Pod log read, Web Console exec.
      4. Gateway API: after creating an access route, verify Gateway Accepted/Programmed and HTTPRoute Accepted/ResolvedRefs/Programmed.
      5. OIDC: complete login, bind external identity, validate callback URL and issuer.
      6. Prometheus/Grafana: scrape API/Worker metrics, import dashboard JSON, and open the iframe URL.

      References