- Prerequisites
- Configure the
remote_development
module in the agent project - Allow the GitLab agent in a group
- Grant workspace users the necessary permissions
Tutorial: Set up the GitLab agent for workspaces
This tutorial shows you how to set up the GitLab agent so users can create and manage workspaces in a project. For this tutorial, the following hierarchy is used:
To set up the GitLab agent, you’re going to:
-
Configure the
remote_development
module in the agent project. - Allow the GitLab agent in a group.
- Grant workspace users the necessary permissions.
Prerequisites
- GitLab agent must be installed and configured.
- You must set up workspace infrastructure.
- You must have administrator access to the instance or the Owner role for the group.
Configure the remote_development
module in the agent project
To configure the remote_development
module in the agent project:
- On the left sidebar, select Search or go to and find your project.
- In your project, create a
.gitlab/agents/<agentName>/config.yaml
file.agentName
is the name of the agent you configured when you set up workspace infrastructure. -
In
config.yaml
, use the following configuration for workspace settings:remote_development: enabled: true dns_zone: "<workspaces.example.dev>" # DNS zone of the URL where workspaces are available
Next, you’ll allow the GitLab agent in a group.
Allow the GitLab agent in a group
When you allow an agent in a group, the group and its subgroups can use that agent. Carefully consider the group where you allow the GitLab agent.
To allow the GitLab agent 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.
- For the GitLab agent, select Allow.
- On the confirmation dialog, select Allow agent.
Now it’s time to grant workspace users the necessary permissions to create and manage workspaces.
Grant workspace users the necessary permissions
You can grant users with at least the Developer role for the workspace and agent projects the necessary permissions to create and manage workspaces.
To grant workspace users the necessary permissions, see:
You’ve done it! Users can now create and manage workspaces in a project.