gitlab-foss/doc/user/workspace/gitlab_agent_configuration.md

stage, group, info, description, title

stage	group	info	description	title
Create	Remote Development	To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments	Configure the GitLab agent for Kubernetes to support your workspace.	GitLab agent for Kubernetes configuration

{{< details >}}

• Tier: Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

• Feature flag remote_development_feature_flag enabled on GitLab.com and GitLab Self-Managed in GitLab 16.0.
• Generally available in GitLab 16.7. Feature flag remote_development_feature_flag removed.

{{< /history >}}

When you set up workspace infrastructure, you must configure a GitLab agent for Kubernetes 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 the GitLab agent for Kubernetes.

• The agent configuration must have the remote_development module enabled, and the required fields of this module must be correctly set.

  {{< alert type="note" >}}

  If you disable the remote_development module on an agent that has active workspaces, those workspaces become unusable. For more information, see workspace settings.

  {{< /alert >}}

• 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

{{< history >}}

• New authorization strategy introduced in GitLab 17.2.

{{< /history >}}

The new authorization strategy replaces the legacy authorization strategy. Group owners and administrators can control which cluster agents host workspaces in their 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:

1. On the left sidebar, select Search or go to and find your group.
2. On the left sidebar, select Settings > Workspaces.
3. In the Group agents section, select the All agents tab.
4. From the list of available agents, find the agent with status Blocked, and select Allow.
5. 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:

1. On the left sidebar, select Search or go to and find your group.
2. On the left sidebar, select Settings > Workspaces.
3. In the Group agents section, select the Allowed agents tab.
4. From the list of allowed agents, find the agent you want to remove, and select Block.
5. 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.

{{< alert type="note" >}}

Removing an allowed cluster agent from a group does not immediately stop running workspaces using the agent. Running workspaces stop when they are automatically terminated or manually stopped.

{{< /alert >}}

Allow a cluster agent for workspaces on the instance

{{< history >}}

• Introduced in GitLab 18.2.

{{< /history >}}

Prerequisites:

• You must set up workspace infrastructure.
• You must have agents with remote development enabled.
• You must have administrator access to the instance.

To allow a cluster agent for workspaces on the instance:

1. On the left sidebar, at the bottom, select Admin.
2. On the left sidebar, select Settings > General.
3. Expand Available agents for workspaces.
4. From the list of agents with workspaces enabled, find the agent you want to allow, and select the availability toggle.

Remove an allowed cluster agent for workspaces on the instance

{{< history >}}

• Introduced in GitLab 18.2.

{{< /history >}}

Prerequisites:

• You must have administrator access to the instance.

To remove an allowed cluster agent from the instance:

1. On the left sidebar, at the bottom, select Admin.
2. On the left sidebar, select Settings > General.
3. Expand Available agents for workspaces.
4. From the list of allowed agents, find the agent you want to remove, and clear the availability toggle.

{{< alert type="note" >}}

Removing an allowed cluster agent from an instance does not immediately stop running workspaces using the agent. Running workspaces stop when they are automatically terminated or manually stopped.

{{< /alert >}}

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 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

• Tutorial: Set up the GitLab for Kubernetes
• Workspace settings
• Workspace configuration
• Troubleshooting Workspaces