- Set up workspace infrastructure
- Create a workspace
- Connect to a workspace with SSH
- Related topics
- Troubleshooting
Workspace configuration
-
Introduced in GitLab 15.11 with a flag named
remote_development_feature_flag
. Disabled by default. - Enabled on GitLab.com and self-managed in GitLab 16.0.
-
Generally available in GitLab 16.7. Feature flag
remote_development_feature_flag
removed.
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. - Set up the GitLab workspaces proxy.
Create a workspace
- Support for private projects introduced in GitLab 16.4.
- Git reference and Devfile location introduced in GitLab 16.10.
- Time before automatic termination renamed to Workspace automatically terminates after in GitLab 16.10.
- Variables introduced in GitLab 17.1.
Prerequisites:
- Ensure your workspace infrastructure is already set up.
- You must have at least the Developer role in the root group.
- In each project where you want to create a workspace, create a devfile:
- On the left sidebar, select Search or go to and find your project.
- In the root directory of your project, create a file named
devfile
. You can use one of the example configurations.
- Ensure the container images used in the devfile support arbitrary user IDs.
To create a workspace:
- On the left sidebar, select Search or go to.
- Select Your work.
- Select Workspaces.
- Select New workspace.
- From the Project dropdown list, select a project with a devfile.
- 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.
- In Devfile location, enter the path to the devfile you use to configure the workspace. If your devfile is not in the root directory of your project, specify a relative path.
- In Workspace automatically terminates after, enter the number of hours until the workspace automatically terminates. This timeout is a safety measure to prevent a workspace from consuming excessive resources or running indefinitely.
- 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.
Connect to a workspace with SSH
- Introduced in GitLab 16.3.
Prerequisites:
- SSH must be enabled for the workspace.
- You must have a TCP load balancer that points to the GitLab workspaces proxy.
To connect to a workspace with an SSH client:
-
Run this command:
ssh <workspace_name>@<ssh_proxy>
-
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
- Quickstart guide for GitLab remote development workspaces
- Set up your infrastructure for on-demand, cloud-based development environments in GitLab
Troubleshooting
Failed to renew lease
when creating a workspace
You might not be able to create a workspace due to a known issue in the GitLab agent for Kubernetes. The following error message might appear in the agent’s log:
{"level":"info","time":"2023-01-01T00:00:00.000Z","msg":"failed to renew lease gitlab-agent-remote-dev-dev/agent-123XX-lock: timed out waiting for the condition\n","agent_id":XXXX}
This issue occurs when an agent instance cannot renew its leadership lease, which results
in the shutdown of leader-only modules including the remote_development
module.
To resolve this issue, restart the agent instance.