Gitlab Workspace: Step-by-Step Guide

You’re encountering the error:

“You can’t create a workspace for this project – No agents available to create workspaces.”

This means your project is missing a GitLab Agent for Kubernetes, which is required for GitLab Workspaces.

✅ Step-by-Step Guide to Set Up GitLab Workspaces

📌 What Is a Workspace?

A Workspace in GitLab is a cloud-based dev environment (similar to GitHub Codespaces), but it needs:

• A configured GitLab Agent for Kubernetes
• A linked Kubernetes cluster

🔧 Prerequisites

1. GitLab Premium or Ultimate
2. A Kubernetes cluster (e.g., GKE, EKS, AKS, Minikube)
3. Access to the GitLab project
4. You are an Owner or Maintainer of the project

🧭 STEP 1: Create a Kubernetes Cluster (if you don’t have one)

You can use:

• GKE: Google Kubernetes Engine
• EKS: Amazon Elastic Kubernetes Service
• AKS: Azure Kubernetes Service
• Minikube: Local dev cluster

🧭 STEP 2: Install GitLab Agent for Kubernetes

1. Go to your GitLab project
2. Navigate to:
   Infrastructure > Kubernetes clusters
   OR
   Settings > CI/CD > GitLab Agent
3. Click Register a new agent
4. Give your agent a name, e.g., gitlab-workspace-agent
5. GitLab will give you a command like: kubectl apply -f https://gitlab.com/api/v4/projects/<PROJECT_ID>/agent_kubernetes_configuration.yaml
6. Copy that command and run it in your Kubernetes cluster

🧭 STEP 3: Configure .gitlab/agents/<agent-name>/config.yaml

Create this file in your repo:

ci_access:
  # Allow CI/CD jobs to access the cluster
  projects:
    - id: your-group/your-project
Code language: PHP (php)

Commit this file to the repository under:

.gitlab/agents/gitlab-workspace-agent/config.yaml

🧭 STEP 4: Enable Workspaces

1. Go to Dev > Workspaces
2. Click New Workspace
3. Select the correct project and the linked agent
4. GitLab will now initialize a dev environment in your Kubernetes cluster

🧪 Troubleshooting That Exact Error

❌ “No agents available to create workspaces”

✅ You must:

• Have a GitLab Agent registered to this project
• Have committed the agent config file to the correct path
• Be using GitLab SaaS or a GitLab instance that supports Workspaces

📝 Official Docs

• GitLab Workspaces Overview
• GitLab Kubernetes Agent Setup

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.