Configure workspaces
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
You can use workspaces to create and manage isolated development environments for your GitLab projects. Each workspace includes its own set of dependencies, libraries, and tools, which you can customize to meet the specific needs of each project.
Set up workspace infrastructure
Before you create a workspace, you must set up your infrastructure only once. To set up infrastructure for workspaces:
- Set up a Kubernetes cluster that the GitLab agent supports. See the supported Kubernetes versions.
- Ensure autoscaling for the Kubernetes cluster is enabled.
- In the Kubernetes cluster:
- Verify that a default storage class is defined so that volumes can be dynamically provisioned for each workspace.
- Install an Ingress controller of your choice (for example,
ingress-nginx
). - Install and configure the GitLab agent.
- Point
dns_zone
and*.<dns_zone>
to the load balancer exposed by the Ingress controller. This load balancer must support WebSockets. - Set up the GitLab workspaces proxy.
- Optional. Configure sudo access for a workspace.
- Optional. Build and run containers in a workspace.
- Optional. Configure support for private container registries.
Create a workspace
Create a workspace only from trusted projects.
Prerequisites:
- You must set up workspace infrastructure.
- You must have at least the Developer role for the workspace and agent projects.
To create a workspace:
On the left sidebar, select Search or go to and find your project.
Select Edit > New workspace.
From the Cluster agent dropdown list, select a cluster agent owned by the group the project belongs to.
From the Git reference dropdown list, select the branch, tag, or commit hash GitLab uses to create the workspace.
From the Devfile dropdown list, select one of the following:
In Variables, enter the keys and values of the environment variables you want to inject into the workspace. To add a new variable, select Add variable.
Select Create workspace.
The workspace might take a few minutes to start. To open the workspace, under Preview, select the workspace. You also have access to the terminal and can install any necessary dependencies.
Configure support for private container registries
To use images from private container registries:
- Create an image pull secret in Kubernetes.
- Add the
name
andnamespace
of this secret to the GitLab agent configuration.
For more information, see image_pull_secrets
.
Configure sudo access for a workspace
Prerequisites:
- Ensure the container images used in the devfile support arbitrary user IDs.
Sudo access for a workspace does not mean that the container image used
in a devfile can run with a user ID of
0
.
A development environment often requires sudo permissions to install, configure, and use dependencies during runtime. You can configure secure sudo access for a workspace with:
With Sysbox
Sysbox is a container runtime that improves container isolation and enables containers to run the same workloads as virtual machines.
To configure sudo access for a workspace with Sysbox:
- In the Kubernetes cluster, install Sysbox.
- In the GitLab agent for workspaces:
- Set
default_runtime_class
to the runtime class of Sysbox (for example,sysbox-runc
). - Set
allow_privilege_escalation
totrue
.
- Set
With Kata Containers
Kata Containers is a standard implementation of lightweight virtual machines that perform like containers but provide the workload isolation and security of virtual machines.
To configure sudo access for a workspace with Kata Containers:
- In the Kubernetes cluster, install Kata Containers.
- In the GitLab agent for workspaces:
- Set
default_runtime_class
to one of the runtime classes of Kata Containers (for example,kata-qemu
). - Set
allow_privilege_escalation
totrue
.
- Set
With user namespaces
User namespaces isolate the user running inside the container from the user on the host.
To configure sudo access for a workspace with user namespaces:
- In the Kubernetes cluster, configure user namespaces.
- In the GitLab agent for workspaces, set
use_kubernetes_user_namespaces
andallow_privilege_escalation
totrue
.
Build and run containers in a workspace
Development environments often require building and running containers to manage and use dependencies during runtime. To build and run containers in a workspace, see configure sudo access for a workspace with Sysbox.
Connect to a workspace with SSH
Prerequisites:
- You must enable SSH access for the images specified in your devfile. For more information, see update your workspace container image.
- You must configure a TCP load balancer that points to the GitLab workspaces proxy. For more information, see update your DNS records.
To connect to a workspace with an SSH client:
Get the external IP address of your
gitlab-workspaces-proxy-ssh
service:kubectl -n gitlab-workspaces get service gitlab-workspaces-proxy-ssh
Get the name of the workspace:
- On the left sidebar, select Search or go to.
- Select Your work.
- Select Workspaces.
- Copy the name of the workspace you want to connect to.
Run this command:
ssh <workspace_name>@<ssh_proxy_IP_address>
For the password, enter your personal access token with at least the
read_api
scope.
When you connect to gitlab-workspaces-proxy
through the TCP load balancer,
gitlab-workspaces-proxy
examines the username (workspace name) and interacts with GitLab to verify:
- The personal access token
- User access to the workspace
Update your workspace container image
To update your runtime images for SSH connections:
- Install
sshd
in your runtime images. - Create a user named
gitlab-workspaces
to allow access to your container without a password.
FROM golang:1.20.5-bullseye
# Install `openssh-server` and other dependencies
RUN apt update \
&& apt upgrade -y \
&& apt install openssh-server sudo curl git wget software-properties-common apt-transport-https --yes \
&& rm -rf /var/lib/apt/lists/*
# Permit empty passwords
RUN sed -i 's/nullok_secure/nullok/' /etc/pam.d/common-auth
RUN echo "PermitEmptyPasswords yes" >> /etc/ssh/sshd_config
# Generate a workspace host key
RUN ssh-keygen -A
RUN chmod 775 /etc/ssh/ssh_host_rsa_key && \
chmod 775 /etc/ssh/ssh_host_ecdsa_key && \
chmod 775 /etc/ssh/ssh_host_ed25519_key
# Create a `gitlab-workspaces` user
RUN useradd -l -u 5001 -G sudo -md /home/gitlab-workspaces -s /bin/bash gitlab-workspaces
RUN passwd -d gitlab-workspaces
ENV HOME=/home/gitlab-workspaces
WORKDIR $HOME
RUN mkdir -p /home/gitlab-workspaces && chgrp -R 0 /home && chmod -R g=u /etc/passwd /etc/group /home
# Allow sign-in access to `/etc/shadow`
RUN chmod 775 /etc/shadow
USER gitlab-workspaces
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