GitLab agent configuration
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
When you set up workspace infrastructure, you must configure a GitLab agent to support workspaces. This guide assumes that a GitLab agent is already installed in the Kubernetes cluster.
Prerequisites:
- You must complete the setup steps in Tutorial: Set up GitLab agent and proxies.
- The agent configuration must have the
remote_development
module enabled, and the required fields of this module must be correctly set. For more information, see workspace settings. - The agent must be allowed in a group for the purpose of creating workspaces. During workspace creation, users can select allowed agents that are associated with any parent group of the workspace project.
- The workspace creator must have the Developer role to the project of the agent.
Agent authorization in a group for creating workspaces
With the new authorization strategy that replaces the legacy authorization strategy, group owners and administrators can control which cluster agents can be used for hosting workspaces in a group.
For example, if the path to your workspace project is top-level-group/subgroup-1/subgroup-2/workspace-project
, you can use any configured agent for either top-level-group
, subgroup-1
or subgroup-2
group.
%%{init: {'theme':'neutral'}}%% graph TD; classDef active fill:lightgreen, stroke:#green, color:green, stroke-width:1px; topGroup[Top-Level Group, allowed Agent 1] subgroup1[Subgroup 1, allowed Agent 2] subgroup2[Subgroup 2, allowed Agent 3] wp(Workspace Project, Agent 1, 2 & 3 all available) topGroup --> subgroup1 subgroup1 --> subgroup2 subgroup2 --> wp class wp active;
If you allow a cluster agent for a specific group, for example, subgroup-1
,
it is available to create workspaces in all projects under that group.
Consider the scope of the allowed group carefully, as it determines where the cluster agent can
host workspaces.
Allow a cluster agent for workspaces in a group
Prerequisites:
- You must set up workspace infrastructure.
- You must have administrator access to the instance or the Owner role for the group.
To allow a cluster agent for workspaces in a group:
- On the left sidebar, select Search or go to and find your group.
- On the left sidebar, select Settings > Workspaces.
- In the Group agents section, select the All agents tab.
- From the list of available agents, find the agent with status Blocked, and select Allow.
- On the confirmation dialog, select Allow agent.
GitLab updates the status of the selected agent to Allowed, and displays the agent in the Allowed agents tab.
Remove an allowed cluster agent for workspaces in a group
Prerequisites:
- You must set up workspace infrastructure.
- You must have administrator access to the instance or the Owner role for the group.
To remove an allowed cluster agent from a group:
- On the left sidebar, select Search or go to and find your group.
- On the left sidebar, select Settings > Workspaces.
- In the Group agents section, select the Allowed agents tab.
- From the list of allowed agents, find the agent you want to remove, and select Block.
- On the confirmation dialog, select Block agent.
GitLab updates the status of the selected agent to Blocked, and removes the agent from the Allowed agents tab.
Removing an allowed cluster agent from a group does not immediately stop running workspaces using this agent. Running workspaces stop when they are automatically terminated or manually stopped.
Legacy agent authorization strategy
In GitLab 17.1 and earlier, the availability of an agent in a group was not a prerequisite for creating workspaces. You can use any agent in the top-level group of a workspace project to create a workspace, if both of the following are true:
- The remote development module is enabled.
- You have at least the Developer role for the top-level group.
For example, if the path to your workspace project is top-level-group/subgroup-1/subgroup-2/workspace-project
,
you can use any configured agent in top-level-group
and in any of its subgroups.
Configuring user access with remote development
You can configure the user_access
module to access the connected Kubernetes cluster with your GitLab credentials.
This module is configured and runs independently of the remote_development
module.
Be careful when configuring both user_access
and remote_development
in the same GitLab agent.
The remote_development
clusters manage user credentials (such as personal access tokens) as Kubernetes Secrets.
Any misconfiguration in user_access
might cause this private data to be accessible over the Kubernetes API.
For more information about configuring user_access
, see
Configure Kubernetes access.
Related topics
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support