Auto DevOps
Auto Build
Auto Test
Auto Security
Auto Deploy
Learn how GitLab Auto DevOps provides a complete CI/CD pipeline out of the box. From auto build and test to security scanning and deployment, understand what it does, how to customize it, and when to use it.
Auto DevOps
Deploy
GitLab CI/CD
What is Auto DevOps?
Auto DevOps is a pre-configured CI/CD pipeline that GitLab provides out of the box. Instead of writing a .gitlab-ci.yml file, you enable Auto DevOps in your project settings, and GitLab automatically detects your application's language and framework, builds it, runs tests, performs security scans, and deploys it to Kubernetes. The goal is to give every project a production-grade pipeline with zero configuration — a "golden path" that follows best practices by default .
Auto DevOps is built on a set of CI/CD templates that live in GitLab itself. Each template handles one stage of the pipeline: Auto-Build.gitlab-ci.yml, Auto-Test.gitlab-ci.yml, Auto-Deploy.gitlab-ci.yml, and so on. When you enable Auto DevOps, GitLab includes all these templates in your pipeline automatically. The templates use sensible defaults for each language, but every behavior can be customized with CI/CD variables .
Auto DevOps is not for every project. It's designed for applications that follow common conventions — a Node.js app with a package.json, a Python app with a requirements.txt, a Ruby app with a Gemfile. For applications with unusual build requirements, Auto DevOps can be customized, but at some point it's simpler to write your own pipeline. Understanding what Auto DevOps does and when it fits is the key to using it effectively.
Core Principle: Auto DevOps is a starting point, not a straitjacket. Enable it to get a complete pipeline in minutes, then customize the parts that need customization using CI/CD variables.
Auto Build
Detects language, builds a Docker image using Herokuish or Cloud Native Buildpacks, pushes to the registry.
Auto Test
Runs tests based on detected language. Node.js, Python, Ruby, Java, Go, PHP are supported.
Auto Security
Runs SAST, Dependency Scanning, Secret Detection, and Container Scanning automatically.
Auto Code Quality
Runs code quality checks (linting, complexity) and displays results in merge requests.
Auto Deploy
Deploys to Kubernetes using Helm. Creates review apps, staging, and production environments.
Customization
Override any behavior with CI/CD variables. Add your own .gitlab-ci.yml to extend the pipeline.
Enabling Auto DevOps
Enabling Auto DevOps is a two-step process. First, ensure your project has a Kubernetes cluster connected (via the GitLab agent) or that you're using a deployment target Auto DevOps understands. Second, enable Auto DevOps in the project settings: Settings → CI/CD → Auto DevOps → "Default to Auto DevOps pipeline." Once enabled, the next push to the default branch triggers a full Auto DevOps pipeline, and no .gitlab-ci.yml file is needed .
Auto DevOps can be enabled at the project level or inherited from a group or instance. If a group has Auto DevOps enabled by default, every new project in the group gets it automatically. This is useful for organizations that want a consistent baseline across all projects. The setting can be overridden per project if needed.
The first pipeline run is where Auto DevOps detects your language. It looks for well-known files — package.json for Node.js, requirements.txt for Python, Gemfile for Ruby, pom.xml for Java, go.mod for Go — and selects the appropriate build and test templates. If your project doesn't match a known language, Auto DevOps may still work using Herokuish buildpacks, but it's more likely to fail. In that case, customizing or writing your own pipeline is the better path .
# Enabling Auto DevOps (UI)
# Project > Settings > CI/CD > Auto DevOps
# - Default to Auto DevOps pipeline: ✓
# - Deployment strategy: Continuous deployment to production
# or Continuous deployment to production with manual approval
# or Timed incremental rollout to production
# or Manual deployment to production
# Enabling Auto DevOps via API
curl --request PUT \
--header "PRIVATE-TOKEN: " \
--url "https://gitlab.example.com/api/v4/projects/:id" \
--data "auto_devops_enabled=true"
# Enabling at group level (inherited by new projects)
curl --request PUT \
--header "PRIVATE-TOKEN: " \
--url "https://gitlab.example.com/api/v4/groups/:id" \
--data "auto_devops_enabled=true"
# Enabling at instance level (admin only)
# Admin > Settings > CI/CD > Auto DevOps
# What Auto DevOps detects:
# - package.json -> Node.js
# - requirements.txt -> Python
# - Gemfile -> Ruby
# - pom.xml -> Java (Maven)
# - build.gradle -> Java (Gradle)
# - go.mod -> Go
# - composer.json -> PHP
# - index.html -> Static site
# - Dockerfile -> Custom Docker build
# If your project doesn't match, Auto DevOps falls back
# to Herokuish buildpacks, which may or may not work
# After enabling, push a commit to trigger the first pipeline
# GitLab will auto-detect and build
# To disable Auto DevOps:
# Settings > CI/CD > Auto DevOps
# - Default to Auto DevOps pipeline: ✗
Auto DevOps Setup Checklist:
- Connect a Kubernetes cluster (via GitLab agent) or another target
- Enable Auto DevOps in project settings
- Ensure your project matches a supported language
- Set required CI/CD variables (e.g.,
KUBE_INGRESS_BASE_DOMAIN)
- Push a commit to trigger the first pipeline
The Auto DevOps Pipeline
When Auto DevOps is enabled, the pipeline consists of several stages, each implemented by one or more templates. The stages are: build, test, code quality, security, review (for merge requests), deploy (staging), and deploy (production). Each stage can be enabled, disabled, or customized independently. The order is fixed (it follows the standard CI/CD flow), but individual jobs within stages can be configured .
The build stage uses either Herokuish (a buildpack-based builder) or Cloud Native Buildpacks to compile the application into a Docker image. If the project has a Dockerfile, it uses that instead. The resulting image is pushed to the GitLab Container Registry. The test stage runs the language-appropriate test suite. The code quality stage runs linting and static analysis. The security stage runs SAST, dependency scanning, and secret detection. The deploy stage uses Helm to deploy to Kubernetes .
For merge requests, Auto DevOps creates a review app — a temporary environment for reviewers to see the changes live. For the default branch, it deploys to staging and, depending on the deployment strategy, either auto-deploys to production or waits for manual approval. The production deployment uses a Helm chart that's bundled with Auto DevOps, but it can be customized. The whole flow is designed to be safe by default: manual approval for production, review apps for MRs, and automatic rollback on failure .
# The Auto DevOps pipeline stages
# (auto-generated, no .gitlab-ci.yml needed)
stages:
- build
- test
- code_quality
- security
- review
- staging
- production
- cleanup
# Build: creates Docker image
# - Uses Herokuish buildpacks or Cloud Native Buildpacks
# - Or uses Dockerfile if present
# - Pushes to GitLab Container Registry
# Test: runs language-specific tests
# - Node.js: npm test
# - Python: pytest
# - Ruby: rspec
# - Java: mvn test
# - Go: go test
# Code Quality: linting and static analysis
# - Uses CodeClimate analyzers
# - Results displayed in MR
# Security: security scans
# - SAST (static analysis)
# - Dependency Scanning
# - Secret Detection
# - Container Scanning
# - License Scanning
# - Results displayed in MR and security dashboard
# Review: review app for merge requests
# - Deploys a temporary environment
# - URL posted in MR
# - Destroyed when MR closes
# Staging: deploys to staging environment
# - Runs on default branch
# - Uses Helm chart
# Production: deploys to production
# - Runs on default branch
# - Manual or automatic based on strategy
# Cleanup: removes old environments
# - Runs on schedules or after deployment
# The pipeline is defined by included templates:
# include:
# - template: Auto-DevOps.gitlab-ci.yml
# You can override individual jobs:
# include:
# - template: Auto-DevOps.gitlab-ci.yml
#
# variables:
# TEST_DISABLED: "true" # Disable test stage
#
# # Customize build
# build:
# script:
# - echo "My custom build"
# - npm run build:custom
Pipeline Stages in Detail:
- Build: Herokuish, Cloud Native Buildpacks, or Dockerfile
- Test: Language-specific test runner
- Code Quality: CodeClimate analyzers
- Security: SAST, DAST, dependency, container, license scanning
- Review: Temporary environment per MR
- Staging: Helm deployment to staging
- Production: Helm deployment to production (manual or auto)
Customizing Auto DevOps
Auto DevOps is highly customizable through CI/CD variables. Every behavior — which stages run, which scanners are enabled, which Helm chart is used, how deployments roll out — is controlled by a variable. You don't need to modify the templates themselves. Instead, you set variables in project or group settings, and Auto DevOps uses them when constructing the pipeline .
The most commonly customized variables control which stages run. Setting BUILD_DISABLED=true skips the build stage; TEST_DISABLED=true skips tests; CODE_QUALITY_DISABLED=true skips code quality. This is useful when a project has unusual requirements — for example, a documentation-only project that doesn't need tests or deployment. Other variables control deployment: STAGING_ENABLED, INCREMENTAL_ROLLOUT_MODE, PRODUCTION_DEPLOYMENT_STRATEGY .
For more extensive customization, you can override individual jobs. Adding a .gitlab-ci.yml file to a project with Auto DevOps enabled merges the two: Auto DevOps jobs run, and your custom jobs run alongside them. You can also override a specific Auto DevOps job by defining a job with the same name (e.g., build), which replaces the default. This gives you full control without losing the parts of Auto DevOps you want to keep.
# Enable/disable stages
variables:
BUILD_DISABLED: "true"
TEST_DISABLED: "true"
CODE_QUALITY_DISABLED: "true"
SAST_DISABLED: "true"
SECRET_DETECTION_DISABLED: "true"
DEPENDENCY_SCANNING_DISABLED: "true"
CONTAINER_SCANNING_DISABLED: "true"
LICENSE_MANAGEMENT_DISABLED: "true"
DAST_DISABLED: "true"
PERFORMANCE_DISABLED: "true"
# Deployment strategy
variables:
# Options: continuous, manual, timed_incremental, incremental
STAGING_ENABLED: "true"
INCREMENTAL_ROLLOUT_MODE: "manual"
PRODUCTION_DEPLOYMENT_STRATEGY: "manual"
# Custom domain for review apps and staging
variables:
KUBE_INGRESS_BASE_DOMAIN: "example.com"
KUBE_NAMESPACE: "my-app"
# Application configuration
variables:
# For Herokuish builds
ADDITIONAL_HOSTS: "my-app.example.com"
# For custom Dockerfile
DOCKERFILE_PATH: "docker/Dockerfile"
# Custom Helm chart
variables:
# Use a custom chart instead of the default
AUTO_DEVOPS_CHART: "https://example.com/charts/my-app"
AUTO_DEVOPS_CHART_REPOSITORY: "my-repo"
AUTO_DEVOPS_CHART_REPOSITORY_NAME: "my-repo"
AUTO_DEVOPS_CHART_REPOSITORY_USERNAME: "user"
AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD: $CHART_PASSWORD
# Override a specific Auto DevOps job
# (place in .gitlab-ci.yml)
build:
script:
- echo "Custom build"
- npm run build:custom
# Extend Auto DevOps with additional jobs
# (place in .gitlab-ci.yml)
include:
- template: Auto-DevOps.gitlab-ci.yml
my_custom_job:
stage: test
script:
- echo "Custom test"
# Use a different buildpack
variables:
BUILDPACK_URL: "https://github.com/heroku/heroku-buildpack-nodejs"
# Auto DevOps variables (most commonly used):
# BUILD_DISABLED, TEST_DISABLED, CODE_QUALITY_DISABLED
# STAGING_ENABLED, INCREMENTAL_ROLLOUT_MODE
# PRODUCTION_DEPLOYMENT_STRATEGY
# KUBE_INGRESS_BASE_DOMAIN, KUBE_NAMESPACE
# AUTO_DEVOPS_CHART, DOCKERFILE_PATH
Customization Caveats:
- Variables apply globally: A variable set at project level affects all jobs
- Job overrides replace, not merge: Defining a job with the same name replaces the Auto DevOps job
- Include vs. replace: Including
Auto-DevOps.gitlab-ci.yml adds jobs; adding a .gitlab-ci.yml alone replaces everything
- Deployment strategy: Choose carefully — "continuous" auto-deploys to production, "manual" waits for approval
Deployment Strategies
Auto DevOps supports four deployment strategies for production. The strategy determines how and when code reaches production. The default is "manual" for most projects, meaning a developer or approver must click "Deploy" after the staging deployment succeeds. The other options are "continuous" (auto-deploy), "timed incremental" (deploy to a percentage of pods, then increase over time), and "manual incremental" (same, but triggered manually) .
For teams just starting with Auto DevOps, "manual" is the safest choice. It ensures that someone is watching when production changes, which is important until you build confidence in the pipeline. "Continuous" is appropriate for teams with strong test coverage and monitoring. "Timed incremental" and "manual incremental" are more advanced — they roll out changes gradually, giving you time to detect problems before they affect all users.
All strategies use Kubernetes' native deployment features, so rollback is always possible via kubectl rollout undo or GitLab's environment rollback. The choice of strategy doesn't affect rollback capability; it affects how quickly changes reach users and how much control you have over the rollout pace. Choose the strategy that matches your team's confidence and your application's risk profile.
# Deployment strategy options
# Continuous deployment (auto-deploy to production)
variables:
PRODUCTION_DEPLOYMENT_STRATEGY: "continuous"
# Every successful staging deployment auto-deploys to production
# Fastest feedback, but requires strong testing and monitoring
# Manual deployment (default)
variables:
PRODUCTION_DEPLOYMENT_STRATEGY: "manual"
# Staging deploys automatically, production waits for approval
# Safest choice for most teams
# Timed incremental rollout (auto)
variables:
INCREMENTAL_ROLLOUT_MODE: "timed"
INCREMENTAL_ROLLOUT_TIME: "5m"
# Rolls out to 10% of pods, waits 5 minutes, then increases
# Gives time to detect issues before full rollout
# Manual incremental rollout
variables:
INCREMENTAL_ROLLOUT_MODE: "manual"
# Same as timed, but each step requires manual approval
# Most cautious option
# Canary deployment (advanced)
# Not a built-in strategy, but can be configured with
# custom Helm charts and traffic splitting
# Environment variables for deployment
variables:
STAGING_ENABLED: "true" # Deploy to staging
KUBE_NAMESPACE: "my-app" # Kubernetes namespace
KUBE_INGRESS_BASE_DOMAIN: "example.com"
# Rollback (any strategy)
# - Use GitLab environments to roll back to previous deployment
# - Or use kubectl:
# kubectl rollout undo deployment/my-app -n my-app
# - Or use helm rollback:
# helm rollback my-app
Deployment Strategy Guidance:
- New to Auto DevOps: Start with "manual"
- Strong testing and monitoring: "continuous" is viable
- High-risk applications: Use "timed incremental"
- Highly regulated environments: Use "manual incremental"
- Always verify rollback works before enabling continuous deployment
Complete Customization Example
Here's a complete .gitlab-ci.yml that extends Auto DevOps for a Node.js project, disabling stages that aren't needed, customizing the build, and adding a custom test job.
# .gitlab-ci.yml
# Extends Auto DevOps with customizations
include:
- template: Auto-DevOps.gitlab-ci.yml
variables:
# Disable stages we don't need
CODE_QUALITY_DISABLED: "true"
LICENSE_MANAGEMENT_DISABLED: "true"
PERFORMANCE_DISABLED: "true"
DAST_DISABLED: "true"
# Deployment configuration
STAGING_ENABLED: "true"
PRODUCTION_DEPLOYMENT_STRATEGY: "manual"
KUBE_NAMESPACE: "my-app"
KUBE_INGRESS_BASE_DOMAIN: "example.com"
# Build configuration
DOCKERFILE_PATH: "Dockerfile"
# Override the build job
build:
script:
- echo "Custom build for Node.js"
- npm ci
- npm run build:prod
# Add a custom job that runs alongside Auto DevOps
custom_e2e_test:
stage: test
image: node:18
script:
- npm ci
- npm run test:e2e
artifacts:
when: always
reports:
junit: test-results/e2e.xml
rules:
- if: $CI_COMMIT_BRANCH == "main"
# Override test job to skip if no tests
test:
script:
- |
if [ -f package.json ] && grep -q '"test"' package.json; then
npm test
else
echo "No tests configured, skipping"
fi
# Result:
# - Auto DevOps runs: build, test, code quality, security, review, staging, production
# - Code quality, license management, performance, DAST are skipped
# - Build is customized for Node.js
# - Custom e2e test runs on main
# - Production requires manual approval
When to Use Auto DevOps
Auto DevOps is the right choice when you want a complete pipeline quickly and your application follows common conventions. It's especially valuable for new projects that don't yet have a CI/CD pipeline — instead of spending days writing and debugging a .gitlab-ci.yml, you enable Auto DevOps and get a working pipeline in minutes. It's also useful for standardizing pipelines across many projects in an organization.
It's less suitable for projects with unusual build requirements. If your application needs a custom build toolchain, a complex multi-stage Dockerfile, or an unsupported language, Auto DevOps will fight you. In those cases, writing your own pipeline is faster than customizing Auto DevOps to fit. The same is true for projects with very specific security or compliance requirements that don't match Auto DevOps defaults.
Many teams use a hybrid approach: enable Auto DevOps for most projects, but disable it for the ones that need custom pipelines. The organization gets a consistent baseline for the majority of projects, and the exceptions are handled explicitly. This is often the most pragmatic path — Auto DevOps for the 80% that fit, custom pipelines for the 20% that don't.
# Use Auto DevOps when:
# - Project is a new app with a common framework
# - Language is Node.js, Python, Ruby, Java, Go, PHP, or static HTML
# - No unusual build requirements
# - Kubernetes is the deployment target
# - You want a baseline pipeline quickly
# - Standardizing pipelines across many projects
# Write your own pipeline when:
# - Language/framework not supported by buildpacks
# - Complex multi-stage Dockerfile
# - Custom build toolchain
# - Non-Kubernetes deployment target
# - Very specific security or compliance requirements
# - Performance-critical pipelines
# - Complex microservices architecture
# Hybrid approach (recommended for many orgs):
# - Enable Auto DevOps at group level
# - Disable it for specific projects that need custom pipelines
# - Group > Settings > CI/CD > Auto DevOps > Default: ✓
# - Project > Settings > CI/CD > Auto DevOps > Disable: ✗
# Check compatibility before enabling:
# - Is the language supported?
# - Is Kubernetes the target?
# - Are there unusual build steps?
# - Do the default security scans work?
# If unsure, enable it on a test branch first
# (Create a branch, enable Auto DevOps, push, observe)
Auto DevOps in 2025:
- Still supported and maintained by GitLab
- Best for standard apps on Kubernetes
- OIDC and cloud provider integration possible via custom jobs
- Most customization through CI/CD variables
Troubleshooting Auto DevOps
# Pipeline not running
# - Check Auto DevOps is enabled
# - Check project has a Kubernetes cluster (or deployment target)
# - Check the branch is the default branch (or Auto DevOps runs on it)
# Build fails: "No buildpack detected"
# - Check project has a recognized language file (package.json, etc.)
# - Check BUILDPACK_URL is not set incorrectly
# - Consider using a Dockerfile instead
# Build fails: "Container image too large"
# - Use a smaller base image
# - Exclude unnecessary files via .dockerignore
# - Use multi-stage builds
# Test fails: "No tests found"
# - Auto DevOps runs the default test command for the language
# - Override the test job with a custom script
# - Or set TEST_DISABLED=true if no tests
# Deployment fails: "Kubernetes cluster not reachable"
# - Check GitLab agent is installed and connected
# - Check KUBE_CONTEXT is set correctly
# - Check the agent is authorized for the project
# Deployment fails: "Namespace not found"
# - Check KUBE_NAMESPACE is set
# - Ensure namespace exists or create it
# - Auto DevOps may create it automatically
# Review app not accessible
# - Check KUBE_INGRESS_BASE_DOMAIN is set
# - Check DNS is configured for wildcard subdomains
# - Check the ingress is created
# Production deploy not happening
# - Check PRODUCTION_DEPLOYMENT_STRATEGY
# - If "manual", a user must click Deploy
# - Check branch is protected (production deploys may require it)
# Too many security findings (noise)
# - Disable specific scanners: SAST_DISABLED=true, etc.
# - Use severity thresholds
# - Review findings before disabling
# Custom variables not taking effect
# - Check spelling (Auto DevOps variables are case-sensitive)
# - Check scope (project vs group)
# - Check if the variable is overridden by a job-level variable
# Debug: view the generated pipeline
# CI/CD > Pipelines > (pipeline) > View full configuration
# This shows the merged configuration, including Auto DevOps jobs
# Debug: check variables in a job
script:
- env | grep -E 'AUTO_DEVOPS|BUILD_|TEST_|KUBE_'
Frequently Asked Questions
What is Auto DevOps and why would I use it?
Auto DevOps is a pre-configured CI/CD pipeline that GitLab provides out of the box. Enable it in project settings, and GitLab auto-detects your language, builds, tests, scans, and deploys. Use it to get a production-grade pipeline without writing a .gitlab-ci.yml .
Do I need Kubernetes for Auto DevOps?
Most deployment features of Auto DevOps require Kubernetes. But you can still use it for build, test, code quality, and security scanning without Kubernetes — just disable the deploy stages.
How do I customize Auto DevOps?
Use CI/CD variables to change behavior (e.g., TEST_DISABLED=true). For deeper customization, add a .gitlab-ci.yml that includes the Auto DevOps template and overrides specific jobs .
Can I disable individual stages?
Yes. Use the corresponding _DISABLED variable: BUILD_DISABLED, TEST_DISABLED, SAST_DISABLED, etc. Set to "true" to disable.
What's the difference between the deployment strategies?
continuous auto-deploys, manual waits for approval, timed incremental rolls out gradually with time delays, manual incremental requires approval at each step.
How do I roll back an Auto DevOps deployment?
Use GitLab environments: find the last successful deployment and click Rollback. This re-runs the deploy job with the previous commit. Auto DevOps also creates Kubernetes deployments, so kubectl rollout undo works.
Can I use Auto DevOps for a microservices app?
Partially. Auto DevOps works well for single-container apps. For microservices, you typically need a custom pipeline that builds and deploys multiple services. Auto DevOps can be used as a starting point but usually needs customization.
Does Auto DevOps support OIDC for cloud deployments?
Not directly — Auto DevOps deploys to Kubernetes using Helm, not to cloud services. For cloud deployments (S3, Cloud Run, etc.), add custom jobs that use OIDC, or write a custom pipeline.