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 a DevOps/SRE/DevSecOps/Cloud Expert passionate about sharing knowledge and experiences. I have worked at Cotocus. I share tech blog at DevOps School, travel stories at Holiday Landmark, stock market tips at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow , and SEO strategies at Wizbrand.

Do you want to learn Quantum Computing?

Please find my social handles as below;

Rajesh Kumar Personal Website
Rajesh Kumar at YOUTUBE
Rajesh Kumar at INSTAGRAM
Rajesh Kumar at X
Rajesh Kumar at FACEBOOK
Rajesh Kumar at LINKEDIN
Rajesh Kumar at WIZBRAND

Rajesh Kumar DailyLogs