How to Set Up a CI/CD Pipeline with GitLab 2026: Step-by-Step

GitLab’s CI/CD platform handles over 12 billion pipeline executions annually across its 31 million registered users, making it one of the fastest-growing automation platforms in software development. Last verified: April 2026.

Executive Summary

Feature	GitLab CI/CD	GitHub Actions	Jenkins	CircleCI
Native Integration	100% (same platform)	100% (same platform)	Requires plugins	Third-party only
Monthly Cost (Pro)	$29/user	$21/user (GitHub Pro)	Self-hosted (free)	$14-$50/month
Max Concurrent Jobs	500	20	Unlimited	Varies by plan
Container Registry	Built-in	Built-in	Requires integration	Third-party
Setup Time (minutes)	5-10	10-15	30-60	15-20
Free Tier Pipeline Minutes	400/month	2,000/month	N/A	6,000/month
Artifact Storage	100GB free	5GB free	Depends on server	500MB free
YAML Configuration	.gitlab-ci.yml	.github/workflows/*.yml	Groovy/XML	config.yml

Why GitLab CI/CD Differs From Other Platforms

GitLab’s CI/CD engine operates fundamentally differently than GitHub Actions because it’s built directly into GitLab’s architecture rather than bolted on as a separate service. When you push code to a GitLab repository, the platform automatically detects your .gitlab-ci.yml file and starts executing jobs on available runners without requiring any marketplace integrations or third-party webhooks. This native integration reduces configuration overhead by roughly 40 percent compared to GitHub Actions, which requires setting up separate workflow files and often depends on external actions for common tasks.

The runner system in GitLab differs significantly too. GitLab runners are essentially lightweight agents that can run on any machine—your laptop, a Docker container, a Kubernetes cluster, or a cloud VM. You’ll register these runners to your GitLab instance using a single registration token, and they’ll pull jobs from the GitLab server as needed. GitHub Actions, by contrast, uses GitHub-hosted runners that you can’t customize or self-host in the same way, though GitHub does offer self-hosted runners as an alternative. GitLab’s approach gives you far more control over execution environments. A typical enterprise deploying GitLab on-premises installs 15-25 runners across various environments to handle different workload types.

GitLab also includes several pipeline features that GitHub Actions doesn’t natively support without additional tooling. DAG (Directed Acyclic Graph) pipelines let you specify exactly which jobs depend on others, enabling parallel execution of independent tasks far more intelligently than GitHub’s job dependencies. Pipeline schedules run on cron expressions directly in GitLab, eliminating the need for GitHub’s third-party scheduling actions. The security scanning integration is deeper too—GitLab’s SAST (Static Application Security Testing) providers are baked into the platform with results displayed in merge requests, whereas GitHub requires installing security apps separately.

Pricing structures diverge significantly as well. GitLab charges based on compute minutes at different rates depending on your plan level, with runner capacity pooled across your entire namespace. GitHub Actions gives you 2,000 free minutes monthly on GitHub-hosted runners but charges $0.008 per minute for self-hosted runner compute. For a team running 1,000 pipeline minutes monthly on custom infrastructure, GitLab’s 400 free minutes plus $0.0085 per additional minute works out roughly 35 percent cheaper than GitHub’s self-hosted model.

Step-by-Step GitLab CI/CD Pipeline Setup

Step	Action Required	Time Required	Critical for Production	Common Mistakes
1. Create .gitlab-ci.yml	Add file to repository root	3 minutes	Yes	Incorrect YAML indentation, missing stages definition
2. Register GitLab Runner	Execute gitlab-runner register command	5 minutes	Yes	Wrong registration token, choosing wrong executor type
3. Configure Runner Tags	Assign tags to runners for job routing	2 minutes	Partially	Using inconsistent tag naming conventions
4. Test Pipeline Trigger	Push commit to trigger pipeline	2 minutes	Yes	Forgetting to commit .gitlab-ci.yml
5. Enable Shared Runners	Configure group or project settings	1 minute	Conditional	Leaving runners disabled inadvertently
6. Set Environment Variables	Add CI/CD variables in project settings	4 minutes	For deployments	Storing secrets in plain text in YAML

Setting up a functional CI/CD pipeline in GitLab requires six primary steps that most teams can execute in under 20 minutes. The first step involves creating a file called .gitlab-ci.yml in your repository’s root directory. This YAML file describes your entire pipeline, including what stages you’ll run, which jobs execute in each stage, and what commands those jobs perform. A minimal pipeline defining build, test, and deploy stages looks straightforward—you’ll specify image for the Docker container, script for the commands to run, and artifacts to preserve between jobs.

Step two requires installing and registering at least one GitLab runner. You can download the runner binary for Linux, macOS, or Windows from GitLab’s official repository. Installation on a Linux server takes roughly 90 seconds using package managers. Once installed, you’ll run the registration command with your GitLab instance URL and a runner registration token (found in your project’s CI/CD settings). When asked which executor to use, most teams starting out should choose shell or Docker. The shell executor runs jobs directly on the machine where the runner’s installed, while the Docker executor spins up a new container for each job, providing better isolation but slightly slower execution—typically 8-12 seconds overhead per job.

The third step involves assigning tags to your runners so GitLab knows which jobs should execute on which machines. If you’re deploying to a Kubernetes cluster, you might tag a runner with “kubernetes”. If you have a Windows build server, you’d tag a Windows runner with “windows”. Inside your .gitlab-ci.yml file, jobs then specify which tags they require using the tags keyword. A job tagged with docker will only run on runners you’ve tagged with docker, preventing mismatches between job requirements and runner capabilities.

Step four is testing—you’ll commit your .gitlab-ci.yml file to a branch and push it to GitLab. The platform automatically detects the file and starts executing your pipeline. You’ll see real-time logs in the CI/CD section of your project dashboard. Step five involves enabling shared runners if your GitLab instance has them available (GitLab.com provides shared runners to free accounts with 400 minutes monthly). If you’re running GitLab self-hosted, you might not have shared runners available, so your registered runners become critical infrastructure.

The final setup step covers sensitive data. Never paste API keys, database passwords, or private tokens directly into .gitlab-ci.yml. Instead, go to your project’s Settings menu, find CI/CD Variables, and add each sensitive value there. You can mark variables as protected (only available in protected branches) and masked (hidden in logs), adding security layers that prevent accidental exposure. Teams managing more than 20 projects typically use GitLab’s group-level variables to share common secrets across multiple projects.

Key Factors for Successful GitLab Pipeline Implementation

1. Selecting the Right Executor (40% of implementation success)

Your runner executor choice determines how jobs run. The shell executor executes on the host machine directly—it’s fastest (zero startup time) but least isolated. Docker executors create containers per job, providing environment consistency but adding 8-12 seconds per job. Kubernetes executors scale automatically, supporting 50-100 concurrent jobs easily but requiring Kubernetes expertise to configure. A survey of 2,847 GitLab teams showed that 61% use Docker, 23% use shell, 12% use Kubernetes, and 4% use other executors. Most growing teams start with Docker, migrate to Kubernetes around the 20-developer mark.

2. Pipeline Caching Strategy (25% performance improvement)

GitLab caches build artifacts between jobs within a single pipeline and across multiple pipelines if configured. Without caching, your build job reinstalls 187-542 dependencies (depending on tech stack) on every pipeline run, wasting 2-6 minutes per pipeline. By caching your dependency folders (node_modules, .gradle, .m2), you’ll reduce build times by roughly 4 minutes per run. With 30 pipelines running weekly, that’s 120 minutes recovered. A team with 15 developers running 300 monthly pipelines saves approximately 1,200 compute minutes annually through proper caching—roughly $17-34 in cloud costs depending on your infrastructure.

3. Security Scanning Integration (critical for 73% of enterprises)

GitLab’s SAST scanning runs static code analysis automatically on every merge request, detecting vulnerabilities in 27 programming languages without requiring additional tools. Dependency scanning identifies outdated or vulnerable packages. Container scanning checks Docker images in your registry for known vulnerabilities. Container network policies prevent lateral movement in Kubernetes environments. A typical enterprise with 150 developers catches approximately 340-510 security issues annually through GitLab’s scanning, with SAST catching 52% of issues, dependency scanning finding 31%, and container scanning identifying 17%.

4. Deployment Environment Configuration (essential for 89% of teams)

GitLab’s environment feature tracks which code versions are deployed where. You can set up distinct environments for staging, production, and canary deployments. When configured properly, GitLab shows deployment history, rollback options, and environment-specific variables. Teams using environments see 34% fewer production incidents because developers can clearly see what’s running where. The feature requires specifying environment names in your deploy jobs and setting up manual approvals for sensitive deployments—roughly 10 minutes of additional configuration per environment.

5. Runner Capacity Planning (determines whether pipelines queue)

Each runner can handle between 1 and 8 concurrent jobs depending on the executor and your server specs. A team with 15 developers committing code throughout the day generates roughly 180-240 pipeline executions weekly. If each job takes 3-8 minutes, you’ll need approximately 12-18 concurrent job capacity to prevent excessive queuing. Underestimating capacity causes developers to wait 15-45 minutes for pipelines, reducing productivity. A runner on a 4-core server with 8GB RAM handles 4 concurrent Docker jobs comfortably. Enterprises managing 500+ developers typically maintain 100-200 runner instances across multiple machines.

How to Use This Information in Your Organization

For Individual Developers: Start with a simple two-stage pipeline (build and test) that runs on GitLab’s shared runners if you’re using GitLab.com. Create your .gitlab-ci.yml file using GitLab’s pipeline editor, which validates YAML syntax in real-time and shows templates for popular frameworks. Test locally using gitlab-runner exec to run jobs on your laptop before pushing to the server. This catches configuration errors before wasting shared runner minutes.

For Small Teams (5-20 developers): Register one shared Docker runner on an existing company server (you probably have a spare 4-core machine somewhere). Set up caching for your primary build artifact directories. Configure three environments: development (auto-deploy), staging (manual deploy), and production (manual deploy with approval gates). Add SAST scanning immediately—it catches vulnerable dependencies that developers miss code review. Enable the CI/CD analytics dashboard to understand which jobs consume the most compute time, then optimize those first.

For Larger Organizations (50+ developers): Implement Kubernetes-based runners that auto-scale from 0 to 80 concurrent jobs, eliminating idle runner overhead. Set up runner groups so different teams can use dedicated runners matching their needs (frontend teams use different Docker images than backend teams). Implement GitLab’s environment tracking with manual approval gates for production. Monitor pipeline metrics weekly—average duration, success rates, and cost per pipeline—to identify optimization opportunities. Connect your deployment pipeline to your incident tracking system so incident responders see which deployment introduced a problem.

Frequently Asked Questions

What’s the difference between GitLab CI/CD and a traditional CI/CD server like Jenkins?

Jenkins is a self-hosted application that you install on a server, configure through a web interface or Groovy code, and manage independently. GitLab CI/CD is built directly into GitLab itself—you define pipelines in .gitlab-ci.yml files that live in your repository, making them version-controlled alongside your code. Jenkins requires installing plugins for nearly every integration (GitHub, Docker, deployment tools), whereas GitLab includes integrations natively. Jenkins offers more flexibility for complex scenarios but requires DevOps expertise to maintain; GitLab prioritizes simplicity and requires less configuration overhead. For teams already using GitLab for version control, CI/CD integration is immediate. For teams using GitHub or Bitbucket, Jenkins becomes more attractive because you avoid vendor lock-in.

How many runners do I need for my team?

This depends on your team size and commit frequency. A rule of thumb: divide your expected daily pipeline executions by 8 (hours) to get hourly execution rate, then multiply by your average job duration in minutes to calculate required concurrent capacity. A 10-developer team committing 40 times daily with 5-minute average job duration needs roughly 3-4 concurrent jobs. A 50-developer team committing 300 times daily with the same 5-minute average needs 25-30 concurrent capacity. Most teams start with one runner and add more when pipelines begin queuing for more than 5 minutes. Cloud-based runners (AWS EC2, Google Cloud, DigitalOcean) scale automatically, so you don’t need to predict capacity precisely.

Can I run GitLab CI/CD on Kubernetes?

Absolutely—this is a popular approach for teams with Kubernetes expertise. The GitLab Kubernetes executor creates a new pod for each job, providing excellent isolation and automatic scaling. You’ll install the GitLab runner on your cluster using Helm charts (takes about 8-10 minutes), configure the Kubernetes executor, and specify persistent volume claims for artifact storage. This setup scales from 0 to 500 concurrent jobs automatically, costs nothing when idle, and integrates seamlessly with Kubernetes RBAC security policies. However, it requires understanding Kubernetes fundamentals and monitoring pod resource usage to prevent cluster overload. Teams without Kubernetes experience should stick with Docker or shell executors.

How do I secure sensitive data in my pipelines?

Never commit credentials to your repository. Instead, use GitLab’s CI/CD Variables feature to store API keys, database passwords, and authentication tokens securely. Mark variables as protected (available only in protected branches) and masked (hidden in job logs). For extremely sensitive values like production database credentials, use GitLab’s integration with external secret management systems like HashiCorp Vault or AWS Secrets Manager. This way, your pipeline retrieves the actual value at runtime without storing it in GitLab. For local testing, use a .env file that’s gitignored. Regularly rotate credentials stored in GitLab variables—set a reminder every 90 days to generate new API keys and update them.

What happens if my runner goes offline or crashes?

Jobs queued for that runner will wait indefinitely unless you set timeout rules or have multiple runners with the same tags. This is why tag your runners by purpose (docker, kubernetes, windows) rather than by hostname. If you tag two runners with “docker”, GitLab will distribute jobs across both. If one crashes, the other picks up the queue automatically. For production environments, use at least 2-3 runners per workload type. Monitor runner health using GitLab’s admin dashboard (shows online/offline status and job queue depth). Most teams implement automatic runner restarts using systemd or Kubernetes health checks so crashed runners come back online within 30-60 seconds without manual intervention.