gitlab-agent

module

v19.3.0 Latest Latest Go to latest Published: Aug 20, 2026 License: MIT

README ¶

GitLab Relay

GitLab Relay is a server-side component deployed alongside GitLab. It lets GitLab reach into environments it cannot dial into — Kubernetes clusters behind a firewall or NAT, CI infrastructure, remote development workspaces.

Agents (such as agentk) run inside those environments and open a long-lived bidirectional gRPC stream out to Relay. Relay then tunnels requests from GitLab back down that connection, inverting the usual client-server relationship so no inbound access to the agent's network is needed.

Note: GitLab Relay was formerly known as the Kubernetes Agent Server (KAS). The name kas is still widely used.

What runs on Relay

Relay is a modular monolith. It hosts:

GitLab Agent for Kubernetes — the original use case, and an active in-cluster component for GitLab ↔ Kubernetes integration tasks
Operational Container Scanning
Remote Development (Workspaces)
Job Router and Runner Controllers
AutoFlow
GitLab CD

Components in this repository

Binary	Runs	Description
`kas`	With GitLab	GitLab Relay itself
`agentk`	In a Kubernetes cluster	GitLab Agent for Kubernetes
`agentw`	In a Kubernetes cluster	GitLab Agent for Remote Development Workspace
`autoflow`	Locally	AutoFlow command line utility
`autocorectl`	Locally	Administer an autocore deployment

Relay also serves agents that live outside this repository, such as the runner and runner controllers used by the Job Router.

Development

See the development guide.

Documentation

The full set is in the doc directory. User-facing documentation is published on docs.gitlab.com.

Contributing

See CONTRIBUTING.md.

Support

Report bugs and request features in the issue tracker. For security issues, follow the GitLab responsible disclosure process — do not open a public issue.

Third-party trademarks

Kubernetes is a registered trademark of The Linux Foundation.

Directories ¶

Path	Synopsis
cmd
agentk command
agentw command
autocorectl command
autoflow command
kas command
internal
agentwcfg
api Package api contains internal APIs that are shared by agent and server code.	Package api contains internal APIs that are shared by agent and server code.
autocore
autocore/admin
autocore/persistence
autocore/persistence/central_migrations
autocore/persistence/workflow_migrations
autoflow
cmd
cmd/agent
cmd/agentk
cmd/agentw
cmd/autocorectl
cmd/autocorectl/central
cmd/autoflow
cmd/autoflow/commands/client
cmd/kas
flowcore
gitaly
gitaly/vendored/backoff Package backoff implements exponential backoff mechanism based on gRPC's backoff algorithm https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md	Package backoff implements exponential backoff mechanism based on gRPC's backoff algorithm https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md
gitaly/vendored/client
gitaly/vendored/dnsresolver
gitaly/vendored/gitalyauth
gitaly/vendored/gitalypb
gitaly/vendored/grpc/client
gitaly/vendored/grpc/protoregistry
gitaly/vendored/protoutil
gitaly/vendored/structerr
gitlab
gitlab/api
it
module/agent2kas_tunnel
module/agent2kas_tunnel/agent
module/agent2kas_tunnel/agentk
module/agent2kas_tunnel/agentw
module/agent2kas_tunnel/router
module/agent2kas_tunnel/server
module/agent_configuration
module/agent_configuration/agentk
module/agent_configuration/rpc
module/agent_configuration/server
module/agent_registrar
module/agent_registrar/agent
module/agent_registrar/agentk
module/agent_registrar/agentk_rpc
module/agent_registrar/agentw
module/agent_registrar/agentw_rpc
module/agent_registrar/runnerc_rpc
module/agent_registrar/server
module/agent_tracker
module/agent_tracker/rpc
module/agent_tracker/server
module/autoflow
module/autoflow/builtin_modules
module/autoflow/builtin_modules/event Package event implements the built-in AutoFlow module that emits events to the Events Platform.	Package event implements the built-in AutoFlow module that emits events to the Events Platform.
module/autoflow/builtin_modules/gitlab Package gitlab implements the built-in AutoFlow module that calls the GitLab REST API.	Package gitlab implements the built-in AutoFlow module that calls the GitLab REST API.
module/autoflow/builtin_modules/kubernetes Package kubernetes implements the built-in AutoFlow module that reads objects from the Kubernetes API of a cluster reachable through an agentk.	Package kubernetes implements the built-in AutoFlow module that reads objects from the Kubernetes API of a cluster reachable through an agentk.
module/autoflow/builtin_modules/modtool Package modtool holds conversions between AutoFlow values and the pieces of an HTTP request and response, shared by the built-in modules that call an API.	Package modtool holds conversions between AutoFlow values and the pieces of an HTTP request and response, shared by the built-in modules that call an API.
module/autoflow/builtin_modules/policy Package policy implements the built-in AutoFlow module that asks the governance decision API whether an action is allowed.	Package policy implements the built-in AutoFlow module that asks the governance decision API whether an action is allowed.
module/autoflow/rpc
module/autoflow/server
module/configuration_project
module/configuration_project/rpc
module/configuration_project/server
module/event_tracker
module/event_tracker/server
module/events_platform
module/events_platform/pubsub
module/events_platform/pubsub/redis
module/events_platform/rpc
module/events_platform/server
module/flux
module/flux/agentk
module/flux/rpc
module/flux/server
module/gitlab_access
module/gitlab_access/agentk
module/gitlab_access/rpc
module/gitlab_access/server
module/google_profiler
module/google_profiler/agent
module/google_profiler/agentk
module/google_profiler/agentw
module/google_profiler/server
module/job_router
module/job_router/rpc
module/job_router/server
module/kas2agentk_tunnel
module/kas2agentk_tunnel/agentk
module/kas2agentk_tunnel/router
module/kas2agentk_tunnel/server
module/kubernetes_api
module/kubernetes_api/agentk
module/kubernetes_api/agentk/watch_graph
module/kubernetes_api/agentk/watch_graph/vendored/github.com/fluxcd/helm-controller/api
module/kubernetes_api/agentk/watch_graph/vendored/github.com/fluxcd/helm-controller/api/v2
module/kubernetes_api/agentk/watch_graph/vendored/github.com/fluxcd/kustomize-controller/api
module/kubernetes_api/agentk/watch_graph/vendored/github.com/fluxcd/kustomize-controller/api/v1
module/kubernetes_api/agentk/watch_graph/vendored/github.com/fluxcd/notification-controller/api
module/kubernetes_api/agentk/watch_graph/vendored/github.com/fluxcd/notification-controller/api/v1
module/kubernetes_api/agentk/watch_graph/vendored/github.com/fluxcd/notification-controller/api/v1beta3
module/kubernetes_api/agentk/watch_graph/vendored/github.com/fluxcd/pkg/apis/kustomize
module/kubernetes_api/agentk/watch_graph/vendored/github.com/fluxcd/source-controller/api
module/kubernetes_api/agentk/watch_graph/vendored/github.com/fluxcd/source-controller/api/v1
module/kubernetes_api/agentk/watch_graph/vendored/k8s.io/api/apps/v1
module/kubernetes_api/agentk/watch_graph/vendored/k8s.io/api/autoscaling/v1
module/kubernetes_api/agentk/watch_graph/vendored/k8s.io/api/autoscaling/v2
module/kubernetes_api/agentk/watch_graph/vendored/k8s.io/api/batch/v1
module/kubernetes_api/agentk/watch_graph/vendored/k8s.io/api/core
module/kubernetes_api/agentk/watch_graph/vendored/k8s.io/api/core/v1
module/kubernetes_api/agentk/watch_graph/vendored/k8s.io/api/events/v1
module/kubernetes_api/agentk/watch_graph/vendored/k8s.io/api/networking
module/kubernetes_api/agentk/watch_graph/vendored/k8s.io/api/networking/v1
module/kubernetes_api/agentk/watch_graph/vendored/k8s.io/api/rbac/v1
module/kubernetes_api/agentk/watch_graph/vendored/k8s.io/api/storage
module/kubernetes_api/agentk/watch_graph/vendored/k8s.io/api/storage/v1
module/kubernetes_api/agentk/watch_graph/vendored/sigs.k8s.io/gateway-api/apis
module/kubernetes_api/agentk/watch_graph/vendored/sigs.k8s.io/gateway-api/apis/v1
module/kubernetes_api/rpc
module/kubernetes_api/server
module/kubernetes_api/server/watch_aggregator
module/managed_resources
module/managed_resources/rpc
module/managed_resources/server
module/modagent
module/modagentk
module/modagentw
module/modserver
module/modshared
module/notifications
module/notifications/rpc
module/notifications/server
module/observability
module/observability/agent
module/observability/agentk
module/observability/agentw
module/observability/server
module/remote_development
module/remote_development/agentk
module/remote_development/agentk/k8s
module/remote_development/agentk/util
module/runner_controller
module/runner_controller/rpc
module/runner_controller/server
module/server_info
module/server_info/rpc
module/server_info/server
module/starboard_vulnerability
module/starboard_vulnerability/agentk
module/starboard_vulnerability/agentk/converter
module/starboard_vulnerability/agentk/resources
module/usage_metrics
module/usage_metrics/server
module/workspaces
module/workspaces/agentw
module/workspaces/rpc
module/workspaces/server
server_api Package server_api contains internal APIs that are used by server/kas code.	Package server_api contains internal APIs that are used by server/kas code.
tool
tool/cache
tool/cryptoz
tool/errz
tool/featureflag
tool/git
tool/grpctool
tool/grpctool/test
tool/httpz
tool/ioz
tool/jwttool
tool/k8stool
tool/logz
tool/mathz
tool/memz
tool/metric
tool/nettool
tool/pgtool
tool/pgtool/pgmigrate
tool/prototool
tool/redistool
tool/secretz
tool/syncz
tool/testing/flowtest Package flowtest provides the workload abstraction for AutoFlow and autocore testing: a Unit describes one workflow test (how to start it, how to drive it from the outside, and what outcome to expect), a Source produces Units, and the loadtest driver executes them.	Package flowtest provides the workload abstraction for AutoFlow and autocore testing: a Unit describes one workflow test (how to start it, how to drive it from the outside, and what outcome to expect), a Source produces Units, and the loadtest driver executes them.
tool/testing/flowtest/corpus Package corpus holds the pre-defined AutoFlow Units of the flowtest workload.	Package corpus holds the pre-defined AutoFlow Units of the flowtest workload.
tool/testing/flowtest/ledger Package ledger is the loadtest driver's durable record of executed sessions: the authoritative client-side observation a later verifier consumes.	Package ledger is the loadtest driver's durable record of executed sessions: the authoritative client-side observation a later verifier consumes.
tool/testing/flowtest/loadtestmodule Package loadtestmodule provides a compiled-in AutoFlow module for testing.	Package loadtestmodule provides a compiled-in AutoFlow module for testing.
tool/testing/flowtest/scenarios
tool/testing/flowtest/scenarios/scenariospb
tool/testing/flowtest/sources
tool/testing/matcher
tool/testing/mock_agent2kas_router Package mock_agent2kas_router is a generated GoMock package.	Package mock_agent2kas_router is a generated GoMock package.
tool/testing/mock_agent_tracker Package mock_agent_tracker is a generated GoMock package.	Package mock_agent_tracker is a generated GoMock package.
tool/testing/mock_autocore Package mock_autocore is a generated GoMock package.	Package mock_autocore is a generated GoMock package.
tool/testing/mock_autoflow Package mock_autoflow is a generated GoMock package.	Package mock_autoflow is a generated GoMock package.
tool/testing/mock_cache Package mock_cache is a generated GoMock package.	Package mock_cache is a generated GoMock package.
tool/testing/mock_cmd_agent Package mock_cmd_agent is a generated GoMock package.	Package mock_cmd_agent is a generated GoMock package.
tool/testing/mock_event_tracker Package mock_event_tracker is a generated GoMock package.	Package mock_event_tracker is a generated GoMock package.
tool/testing/mock_flowcore Package mock_flowcore is a generated GoMock package.	Package mock_flowcore is a generated GoMock package.
tool/testing/mock_gitaly Package mock_gitaly is a generated GoMock package.	Package mock_gitaly is a generated GoMock package.
tool/testing/mock_gitlab_access Package mock_gitlab_access is a generated GoMock package.	Package mock_gitlab_access is a generated GoMock package.
tool/testing/mock_internalgitaly Package mock_internalgitaly is a generated GoMock package.	Package mock_internalgitaly is a generated GoMock package.
tool/testing/mock_k8s Package mock_k8s is a generated GoMock package.	Package mock_k8s is a generated GoMock package.
tool/testing/mock_kubernetes_api Package mock_kubernetes_api is a generated GoMock package.	Package mock_kubernetes_api is a generated GoMock package.
tool/testing/mock_modagent Package mock_modagent is a generated GoMock package.	Package mock_modagent is a generated GoMock package.
tool/testing/mock_modserver Package mock_modserver is a generated GoMock package.	Package mock_modserver is a generated GoMock package.
tool/testing/mock_modshared Package mock_modshared is a generated GoMock package.	Package mock_modshared is a generated GoMock package.
tool/testing/mock_otel Package mock_otel is a generated GoMock package.	Package mock_otel is a generated GoMock package.
tool/testing/mock_prototool
tool/testing/mock_redis Package mock_redis is a generated GoMock package.	Package mock_redis is a generated GoMock package.
tool/testing/mock_rpc Package mock_rpc is a generated GoMock package.	Package mock_rpc is a generated GoMock package.
tool/testing/mock_stdlib Package mock_stdlib is a generated GoMock package.	Package mock_stdlib is a generated GoMock package.
tool/testing/mock_tool Package mock_tool is a generated GoMock package.	Package mock_tool is a generated GoMock package.
tool/testing/mock_tunnel_rpc Package mock_tunnel_rpc is a generated GoMock package.	Package mock_tunnel_rpc is a generated GoMock package.
tool/testing/mock_tunnel_tunserver Package mock_tunnel_tunserver is a generated GoMock package.	Package mock_tunnel_tunserver is a generated GoMock package.
tool/testing/mock_usage_metrics Package mock_usage_metrics is a generated GoMock package.	Package mock_usage_metrics is a generated GoMock package.
tool/testing/testautocore
tool/testing/testautocore/helper Package helper (imported as testautocore_helper) provides low-level SQL assertions and mutations used by autocore tests.	Package helper (imported as testautocore_helper) provides low-level SQL assertions and mutations used by autocore tests.
tool/testing/testautoflow
tool/testing/testcontainerz
tool/testing/testgitlab
tool/testing/testhelpers
tool/testing/testk8s Package testk8s provides a fake Kubernetes cluster API for tests.	Package testk8s provides a fake Kubernetes cluster API for tests.
tool/testing/testlogger
tool/testing/testotel Package testotel provides helpers for asserting on OpenTelemetry metrics in tests.	Package testotel provides helpers for asserting on OpenTelemetry metrics in tests.
tool/testing/testproto
tool/timez
tool/tlstool
tool/tracing Package tracing provides helpers around the OpenTelemetry tracing API.	Package tracing provides helpers around the OpenTelemetry tracing API.
tool/version
tool/wstunnel
vendored/k8s.io/apiserver/pkg/endpoints/handlers/negotiation Package negotiation contains media type negotiation logic.	Package negotiation contains media type negotiation logic.
pkg
agentcfg
constraint
entity
entity/agentk
entity/agentw
entity/runnerc
event
kascfg
scripts
loadtests/autoflow/cmd command

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL