docs.gitlab.com
Open in
urlscan Pro
2600:1901:0:7b8a::
Public Scan
URL:
https://docs.gitlab.com/runner/install/windows.html
Submission: On August 30 via manual from US — Scanned from US
Submission: On August 30 via manual from US — Scanned from US
Form analysis 1 forms found in the DOM
<form class="gl-relative" __bizdiag="0" __biza="WJ__">
<div class="gl-search-box-by-type"><svg data-testid="search-icon" role="img" aria-hidden="true" class="gl-search-box-by-type-search-icon gl-icon s16 gl-fill-current">
<use href="/assets/images/icons.svg#search"></use>
</svg> <input type="search" placeholder="Search GitLab documentation" autocomplete="off" class="gl-form-input form-control gl-search-box-by-type-input-borderless" aria-label="Search" id="__BVID__19"> <!----></div><kbd
title="Use the shortcut keys<br><kbd>/</kbd> or <kbd>s</kbd> to start a search" class="gl-absolute gl-z-index-1 gl-bg-gray-100 gl-text-gray-700">/</kbd>
</form>Text Content
Docs
*
/
* What's new?
v17.4
17.4 (not yet released)
--------------------------------------------------------------------------------
17.3 (recently released)
17.2
17.1
--------------------------------------------------------------------------------
16.11
15.11
--------------------------------------------------------------------------------
Archives
* Get free trial
Tutorials
Find your way around GitLab
Tutorial: Use the left sidebar to navigate GitLab
Learn Git
Plan and track your work
Build your application
Secure your application
Manage your infrastructure
Extend with GitLab
Find more tutorials
Subscribe
Choose a subscription
GitLab.com
Free user limit
Free push limit
Read-only namespaces
Storage
GitLab self-managed
Activate Enterprise Edition
GitLab Dedicated
Subscription add-ons
Community programs
Customers Portal
Quarterly reconciliation
Compute quota
Features available to Starter and Bronze subscribers
Install
Requirements
PostgreSQL extensions
Installation methods
Linux package (Omnibus)
Architecture
Omnibus packages and images
Package information
Package defaults
Package licensing
Package signatures
PostgreSQL versions
Installation
Deprecation policy
Supported OSes
Install JiHu Edition
Configure
Action Cable
Backups
Configuration options
Custom environment variables
Database
GitLab Mattermost
High availability roles
Logs
Microsoft Graph Mailer
NGINX
Troubleshooting
Gitaly Cluster
Prometheus
Puma
Raspberry Pi
Redis
SMTP
Rake tasks
SSL
Troubleshooting
DNS
Image scaling
Memory-constrained environments
Release process
Maintain
Troubleshooting
Helm chart (Kubernetes)
Install
Verify CNG images
Test the GitLab chart on GKE or EKS
Install prerequisites
Chart versions
Provenance
Secrets
RBAC
Storage
TLS
Set up cloud resources
Azure Kubernetes Service
Amazon EKS
Google Kubernetes Engine
OpenShift Origin
Oracle Container Engine for Kubernetes
Deploy the Helm chart
Deployment options
Configure
Globals
certmanager-issuer chart
GitLab subcharts
Gitaly chart
GitLab Exporter chart
GitLab Pages chart
GitLab Runner chart
GitLab Shell chart
KAS chart
Mailroom chart
Migrations chart
Praefect chart
Sidekiq chart
Spamcheck chart
Toolbox chart
Webservice chart
HAProxy chart
Minio chart
NGINX chart
NGINX chart fork
Registry chart
Metadata database
Traefik chart
Zoekt chart
shared-secrets job
Advanced
Custom Docker images
External database
Set up external PostgreSQL database
External Gitaly
Set up external Gitaly
External GitLab Pages
External Mattermost
External Nginx
External object storage
Configure MinIO Configure Workload Identity Federation Configure Azure MinIO
gateway Configure IAM roles for AWS
External Redis
Set up external Redis
FIPS-compliant images
Geo
Internal TLS between services
Multiple databases
Persistent volumes
Red Hat UBI-based images
Upgrade
Database upgrade
Release notes 8.0
Release notes 7.0
Release notes 6.0
Backup and Restore
Backup
Restore
Migration guides
Migrate from the Linux package
Migrate to the Linux package
Migrate between Helm versions
Migrate to MinIO
Uninstall
Troubleshooting
Operator (Kubernetes)
Install
Backup and restore
Upgrade GitLab
Support for Git over SSH
Upgrade the Operator
Ingress in OpenShift
OpenShift support
RedHat-certified images
Security context constraints
Troubleshooting
Docker
Installation
Configuration
Backup and restore
Upgrade
Troubleshooting
Self-compiled (source)
Install under a relative URL
Cloud providers
Azure
Google Cloud Platform (GCP)
Amazon Web Services (AWS)
Offline GitLab
Offline GitLab installation
Reference architectures
Up to 20 RPS or 1,000 users
Tutorial: Install and secure a single node GitLab instance
Up to 40 RPS or 2,000 users
Up to 60 RPS or 3,000 users
Up to 100 RPS or 5,000 users
Up to 200 RPS or 10,000 users
Up to 500 RPS or 25,000 users
Up to 1,000 RPS or 50,000 users
Steps after installing
Upgrade GitLab
Plan an upgrade
Background migrations
Troubleshooting
Upgrade a Linux package instance
Convert to Linux package (Omnibus)
Convert to Enterprise Edition
Package signatures
Downgrade
Troubleshooting
Upgrade a self-compiled instance
Patch versions
Change from Community Edition to Enterprise Edition
GitLab 17 changes
GitLab 16 changes
GitLab 15 changes
GitLab 14 changes
Zero-downtime upgrades for multi-node instances
Upgrades with downtime for multi-node instances
Change from Enterprise Edition to Community Edition
Releases and maintenance
Deprecations by version
Terminology
What's new
Install GitLab Runner
Linux
Linux manual install
FreeBSD
macOS
Windows
Docker
Helm chart
GitLab agent
Operator
Bleeding edge releases
Support policy
Configure GitLab Runner
Advanced configuration
Autoscale configuration
Docker Machine Executor autoscale
Autoscale on AWS EC2
Autoscale on AWS Fargate
Commands
Feature flags
macOS setup
Runner Operator on OpenShift
Running behind a proxy
Rate limited requests
Graphical processing units
Self-signed certificates
System services
Speed up job execution
Tutorial: Configure GitLab Runner to use the Google Kubernetes Engine
Troubleshooting
Administer
Getting started
All feature flags
Enable features behind feature flags
Authentication and authorization
ClickHouse
LDAP
LDAP synchronization
LDAP (Google Secure)
Rake tasks
Troubleshooting
OAuth service provider
OmniAuth
AliCloud
Atlassian
Atlassian Crowd (deprecated)
Auth0
AWS Cognito
Azure
Bitbucket Cloud
Generic OAuth2
GitHub
GitLab.com
Google
JWT
Kerberos
Troubleshooting
OpenID Connect OmniAuth
Salesforce
SAML
Configure SCIM
Shibboleth
OpenID Connect identity
Smartcard
Test OIDC/OAuth in GitLab
Vault
Configure your installation
Admin Area
Application cache interval
Compliance
Audit events administration
Audit event streaming for instances
CI/CD
Secure files
External pipeline validation
ClickHouse for analytics
Consul
Cron
Custom HTML header tags
Environment variables
File hooks
Geo sites
Git LFS administration
Git protocol v2
Health Check
Incoming email
Rake tasks
Instance limits
Instance review
Log system
Parse logs with jq
Trace logs based on correlation ID
Merge request approvals
PostgreSQL
Database load balancing
External database service
Monitor external databases
Move instances
Multiple databases
PgBouncer
Replication and failover
Troubleshooting
Standalone packaged database
Upgrade external database
Upgrading operating systems for PostgreSQL
Labels
Load balancer
NFS
Postfix
Redis
Configure the bundled Redis for replication
Configure your own Redis for replication
Standalone Redis configuration
Troubleshooting
Reply by email
Sidekiq
Multiple Sidekiq processes
Processing specific job classes
Sidekiq MemoryKiller
Sidekiq health check
Sidekiq job migration
Sidekiq job size limits
Troubleshooting
S/MIME signing
Repository storage
Gitaly and Geo capabilities
Gitaly and Gitaly Cluster
Configure Gitaly
Concurrency limiting
Timeouts
TLS support
Repository consistency checks
Configure Gitaly Cluster
Gitaly on Kubernetes
Bundle URIs
Example configuration files
Monitoring
Recovery options
Troubleshooting Gitaly
Troubleshooting Gitaly Cluster
Praefect Rake tasks
Object storage
Merge request diffs storage
Static objects external storage
Geo
Setting up Geo
Set up Geo for multiple nodes
Database replication
External PostgreSQL instances
Set up Geo for two single-node sites
Set up Geo for two single-node sites (with external PostgreSQL services)
Configuration
Using a Geo site
Secondary proxying
Secondary runners
Selective synchronization
Upgrading Geo sites
Using object storage
Container registry for a secondary site
Geo security review
Location-aware Git remote URLs
Single Sign On (SSO)
Tuning Geo
Rake tasks
Disable Geo
Removing a Geo site
Supported data types
Frequently asked questions
Troubleshooting
Common errors
Client and HTTP response code errors
Replication errors
Synchronization errors
Validation tests
Geo Glossary
Disaster recovery (Geo)
Planned failover
Bring primary back
Automatic background verification
Troubleshooting
Agent server for Kubernetes
Server hooks
Terraform state
Terraform limits
Timezone
Uploads
Uploads migration Rake tasks
Uploads sanitization Rake tasks
Packages
Container registry
Container registry metadata database
Dependency Proxy
Web terminals
Wikis
Invalidate Markdown cache
Issue closing pattern
Snippets
Host the product documentation
Update your settings
Account and limit settings
Appearance
CI/CD
Custom instance-level project templates
Diff limits
Email
External authorization
Federated Learning of Cohorts (FLoC)
GitLab for Jira Cloud app
Troubleshooting
GitLab for Slack app
GitLab Pages
GitLab Pages for source installations
Troubleshooting
Import and export settings
Instance template repository
IP address restrictions
Job artifacts
Troubleshooting
Job logs
Localization
Maintenance Mode
Polling interval multiplier
Project integrations
Protected paths
Public security contact information
Push event activities limit
Repository checks
Security and Compliance
Sign-in and help page text
Sign-in restrictions
Sign-up restrictions
Spamcheck
System Hooks
Terms of service and privacy policy
Third-party offers
Visibility and access controls
Maintain your installation
Housekeeping
Clean up with Rake tasks
Maintenance Rake tasks
Integrity check Rake task
Access token Rake tasks
Activate GitLab EE with license
Import and export large projects
Troubleshooting
Fast SSH key lookup
Filesystem benchmarking
gitlab-sshd
Rails console
Use SSH certificates
Enable encrypted configuration
Rake tasks
Backup and restore
Back up GitLab
Backup archive process
Back up and restore large reference architectures
Troubleshooting
Restore GitLab
Migrate to a new server
Inactive project deletion
Move repositories
Silent mode
Read-only state
Restart GitLab
Troubleshooting
Apps for a testing environment
Diagnostics tools
GitLab Rails console cheat sheet
Linux cheat sheet
PostgreSQL
Monitor your installation
Performance monitoring
Prometheus
Configure Grafana
Performance bar
GitHub imports
GitLab exporter
GitLab Prometheus metrics
IP allowlist endpoints
Node exporter
PGBouncer exporter
PostgreSQL server exporter
Redis exporter
Registry exporter
Usage statistics
Web exporter
Secure your installation
Limits on SSH keys
Rate limits
Deprecated API
Git HTTP
Git LFS
Git SSH operations
Git abuse
Import and export
Incident management
Issue creation
Note creation
Package registry
Pipeline creation
Projects API
Raw endpoints
Repository files API
User and IP
Groups API
Members API
Users API
Filtering outbound requests
Information exclusivity
Manage the CRIME vulnerability
Enforce two-factor authentication (2FA)
Identity verification
Account email verification
Make new users confirm email
Runners
Proxying assets
Token overview
Troubleshooting
Rotate secrets of third-party integrations
Respond to security incidents
Hardening
General concepts
Application recommendations
CI/CD recommendations
Configuration recommendations
Operating system recommendations
NIST 800-53 compliance
Administer users
Reset user password
Unlock a user
Review abuse reports
Review spam logs
User file uploads
Password storage
Credentials inventory
Custom password length limits
Generated passwords and integrated authentication
Global user settings
Moderate users
Auditor users
External users
Guest users
Internal users
Configure the Libravatar service
Broadcast messages
Email from GitLab
User cohorts
Rake tasks
GitLab Dedicated
Create your GitLab Dedicated instance
Configure your GitLab Dedicated instance
Hosted runners for GitLab Dedicated
Self-hosted large language model
Configure your GitLab Duo features
Troubleshooting your self-managed GitLab Duo setup
Set up your self-hosted model deployment infrastructure
Set up a self-hosted large language model with LiteLLM
Use GitLab
Manage your organization
Tutorial: Set up your organization
Namespaces
Members
Organization
Groups
Manage groups
Group access and permissions
Manage group SSH certificates
Moderate users
Custom group-level project templates
Group access tokens
SAML Group Sync
SAML SSO for GitLab.com groups
Configure SCIM
Troubleshooting
Example group SAML and SCIM configurations
Troubleshooting
Subgroups
Tutorial: Move a personal project to a group
Tutorial: Convert a personal namespace into a group
Git abuse rate limit
Troubleshooting
Sharing projects and groups
Compliance
Audit events
Audit event types
Audit event schema
Audit event streaming for top-level groups
Compliance frameworks
Compliance pipelines
Tutorial: Create a compliance pipeline
Compliance center
Compliance standards adherence dashboard
Compliance violations report
Chain of custody report
Compliance frameworks report
Compliance projects report
License scanning of CycloneDX files
License approval policies
SPDX license list import
Enterprise users
Service accounts
User account options
Active sessions
Comment templates
Contributions calendar
Achievements
Permissions and roles
Custom roles
Available custom permissions
Personal access tokens
Profile preferences
Notification emails
User passwords
Two-factor authentication
Troubleshooting
Report abuse
Delete account
SSH keys
Troubleshooting
GitLab.com settings
Organize work with projects
Getting started
Create a project
Manage projects
Project visibility
Project settings
Description templates
Project access tokens
Deploy keys
Deploy tokens
Share projects
Reserved project and group names
Search
Advanced search
Exact code search
Command palette
Badges
Project topics
Code intelligence
Import and migrate
Bitbucket Cloud
Bitbucket Server
ClearCase
CVS
FogBugz
Gitea
GitHub
GitHub import Rake task
Troubleshooting
GitLab (direct transfer)
Migrate groups and projects
Migrated items
Troubleshooting
GitLab (file export)
Troubleshooting
Jira
Jira migration options
Perforce Helix
Repo by manifest file
Repo by URL
TFVC
System notes
Transfer a project to another namespace
Use a project as a Go package
Tutorial: Build a protected workflow for your project
Troubleshooting
Plan and track work
Getting started
Tutorial: Use GitLab for Scrum
Stand-ups, retrospectives, and velocity
Tutorial: Use GitLab for Kanban
Labels
Iterations
Tutorial: Use GitLab to run an Agile iteration
Milestones
Burndown and burnup charts
Issues
Create issues
Manage issues
Confidential issues
Crosslinking issues
CSV export
CSV import
Design management
Due dates
Emoji reactions
Tutorial: Set up a project for issue triage
Tutorial: Set up a project for idea management
Multiple assignees
Linked issues
Service Desk
Configure Service Desk
Use Service Desk
External participants
Rake tasks
Sorting and ordering issue lists
Weight
Zoom meetings in issues
Issue boards
Tutorial: Set up issue boards for team hand-off
Comments and threads
Tasks
Requirements
Time tracking
Customer relations (CRM)
Wikis
Group wikis
Epics
Manage epics
Linked epics
Epic boards
Test a new look for epics
Roadmaps
Planning hierarchies
Objectives and key results (OKR)
Keyboard shortcuts
Quick actions
Autocomplete characters
Markdown
AsciiDoc
Rich text editor
To-Do List
Learn Git
Getting started
Install Git
Tutorial: Create your first commit
Clone a repository to your local machine
Create a branch for your changes
Add files to your branch
Stash changes for later
Stage, commit, and push changes
Tutorial: Update Git commit messages
Undo changes
Rebase to address merge conflicts
Common Git commands
Tutorial: Update Git remote URLs
Troubleshooting
Manage your code
Getting started
Repositories
Code owners
Syntax and errors
Troubleshooting
Branches
Default branch
Protected branches
File management
CSV files
Explain code
File Blame
File History
GeoJSON files
Git attributes
Jupyter notebook files
Syntax highlighting
Forks
Mirroring
Bidirectional mirroring
Pull mirroring
Push mirroring
Troubleshooting
Managing monorepos
Observability
Troubleshooting
Git LFS
Troubleshooting
Reduce repository size
Tags
Protected tags
Changelogs
Snippets
Locked files
Machine learning model experiments
Model registry
Push rules
Signed commits
Sign commits with GPG
Sign commits with SSH keys
Sign commits and tags with X.509
Signed commits from the GitLab UI
X.509 signatures Rake task
Web Editor
Merge requests
Commits
Commit message templates
Changes
Create merge requests
Draft merge requests
Confidential merge requests
Merge request dependencies
Reviewing and managing merge requests
Merge request widgets
External status checks
Suggestions
GitLab Duo in merge requests
Suggested Reviewers data usage
Approvals
Approval rules
Approval settings
Versions
Manage merge requests
Tutorial: Review a merge request
Workflows
Merge methods
Squash and merge
Auto-merge
Collaborate across forks
Merge conflicts
Cherry pick changes
Reverting changes
Stacked diffs
Export merge requests to CSV
Troubleshooting
Remote development
Web IDE
Workspaces
Workspace configuration
GitLab agent configuration
Tutorial: Set up the GitLab agent
Tutorial: Set up the GitLab workspaces proxy
Tutorial: Create a custom workspace image that supports arbitrary user IDs
Use CI/CD to build your application
Getting started
Tutorial: Your first pipeline
Tutorial: A complex pipeline
Plan a migration to GitLab CI/CD
Migrate from Bamboo
Migrate from CircleCI
Migrate from GitHub actions
Migrate from Jenkins
Migrate a Maven build from Jenkins
Migrate from TeamCity
CI/CD examples
Deployment with Dpl
End-to-end testing
NPM with semantic-release
PHP with PHPunit and atoum
PHP with NPM and SCP
PHP with Laravel and Envoy
CI/CD YAML syntax reference
Optimize your YAML files
Validate syntax
Debug pipelines
Pipeline editor
Artifacts reports
Include examples
Inputs
Workflow examples
Log timestamps
Steps
Tutorial: Set up CI/CD steps
Runners
Tutorial: Create, register, and run your own project runner
Tutorial: Automate runner creation and registration
GitLab-hosted runners
Linux
GPU
macOS
Windows
Manage runners
Register a runner
Migrate to the new runner registration workflow
Runner executors
Custom
libvirt
LXD
Docker
Docker Machine
Docker Autoscaler
Instance
Kubernetes
Troubleshooting
Shell
Supported shells
SSH
Parallels
VirtualBox
Configure runners
Monitor runner performance
Long polling
Scale a fleet of runners
Fleeting library
Runner fleet dashboard
Runner fleet dashboard for groups
Pipelines
Types of pipelines
Merge request pipelines
Troubleshooting
Merged results pipelines
Merge trains
Scheduled pipelines
Trigger a pipeline
Customize pipeline configuration
Pipeline architectures
Pipeline efficiency
Pipeline resource groups
Directed acyclic graph (DAG)
Downstream pipelines
Troubleshooting
Jobs
Control how jobs run
Specify when jobs run with rules
Troubleshooting
Access a terminal for a running job
Format scripts and job logs
Git submodules
Cache and artifacts
Job artifacts
Troubleshooting
Docker
Run CI/CD jobs in Docker containers
Use Docker to build Docker images
Authenticate with registry
Docker Layer Caching
Use kaniko to build Docker images
Tutorial: Use Buildah in a rootless container on OpenShift
CI/CD components
CI/CD component examples
Variables
Predefined CI/CD variables
Where variables can be used
Pipeline security
CI/CD job token
External secrets
ID token authentication
Secure Files
Use Azure Key Vault secrets in GitLab CI/CD
Use GCP Secret Manager secrets in GitLab CI/CD
Tutorial: Use Fortanix Data Security Manager (DSM) with GitLab
Use Sigstore for keyless signing
Connect to cloud services
Configure OpenID Connect in AWS
Configure OpenID Connect in Azure
Configure OpenID Connect with Google Cloud
Authenticating with HashiCorp Vault
Tutorial: Update HashiCorp Vault configuration to use ID Tokens
Services
MySQL service
PostgreSQL service
Redis service
GitLab as a service
Auto DevOps
Requirements
Stages
Customize
CI/CD variables
Multiple Kubernetes clusters
Canary deployments
Upgrade PostgreSQL
Prepare for deployment
Upgrade Auto Deploy dependencies
Deploy to GKE
Deploy to EKS
Deploy to ECS
Deploy to EC2
Troubleshooting
Testing
Accessibility testing
Browser performance testing
Code coverage
Code quality
Troubleshooting
Fail fast testing
Load performance testing
Metrics reports
Test cases
Test coverage visualization
Cobertura Coverage Reports
JaCoCo Coverage Reports
Unit test reports
Unit test report examples
SSH keys
ChatOps
Mobile DevOps
Google Cloud integration
Google IAM
Google Artifact Management
Provisioning runners
Tutorial: Set up the Google Cloud integration
Tutorial: Create a GitLab pipeline to push to Google Artifact Registry
Tutorial: Create and deploy a web service with the Google Cloud Run component
External repository integrations
Bitbucket Cloud
GitHub
Secure your application
Getting started
Application security
Troubleshooting
Security Configuration
Container Scanning
Tutorial: Scan a Docker container for vulnerabilities
Dependency Scanning
Tutorial: Set up dependency scanning
Troubleshooting
Comparison: Dependency Scanning and Container Scanning
Dependency List
Tutorial: Export dependency list
Continuous Vulnerability Scanning
Static Application Security Testing
SAST rules
Customize rulesets
SAST analyzers
GitLab Advanced SAST analyzer
Troubleshooting
Infrastructure as Code (IaC) Scanning
Secret detection
Pipeline secret detection
Detected secrets
Automatic response to leaked secrets
Custom rulesets schema
Secret push protection
Detected secrets
Client-side secret detection
Detected secrets
Dynamic Application Security Testing (DAST)
DAST browser-based analyzer
Migrating from the DAST version 4 browser-based analyzer to DAST version 5
Migrating from the DAST proxy-based analyzer to DAST version 5
Configuration
Requirements
Enabling the analyzer
Customizing analyzer settings
Overriding analyzer jobs
Available CI/CD variables
Authentication
Offline configuration
Vulnerability checks
Troubleshooting
DAST proxy-based analyzer (deprecated)
Troubleshooting
DAST on-demand scan
Authentication
Troubleshooting
API security testing
Configuration
Requirements
Enabling the analyzer
Customizing analyzer settings
Overriding analyzer jobs
Available CI/CD variables
Offline configuration
Vulnerability checks
Performance
Troubleshooting
Run DAST offline
API Security
API Discovery
Web API Fuzz Testing
Configuration
Requirements
Enabling the analyzer
Customizing analyzer settings
Overriding analyzer jobs
Available CI/CD variables
Offline configuration
HTTP Archive format
Performance
Troubleshooting
Coverage-guided fuzz testing
Tutorial: Perform fuzz testing in GitLab
Security Dashboard
Offline environments
Vulnerability Report
View vulnerabilities in a pipeline
Vulnerability Page
Vulnerability severity levels
GitLab Advisory Database
CVE ID requests
Policies
Scan execution policies
Tutorial: Set up a scan execution policy
Merge request approval policies
Tutorial: Set up a merge request approval policy
Pipeline execution policy
Security scanner integration
Secure and Govern glossary
Deploy and release your application
Getting started
Packages & Registries
Package registry
Supported package managers
Supported functionality
Composer
Conan
Debian
Go Proxy
Helm
Maven
npm
NuGet
PyPI
Ruby gems
Yarn
Generic
Dependency proxy for packages
Store all packages in one project
Monorepo workflows
Reduce package registry storage
Build packages
Protected packages
Container registry
Authenticate
Build and push images
Delete images
Protected container repositories
Reduce container registry storage
Reduce container registry data transfers
Troubleshooting
Harbor registry
Terraform module registry
Dependency Proxy
Reduce Dependency Proxy storage
Environments and deployments
Deploy to AWS
Deploy to Amazon ECS
Deploy to Heroku
External deployment tools
Dashboard for Kubernetes
Environments Dashboard
Operations Dashboard
Review apps
Protected environments
Deployment safety
Deployment approvals
Configure Kubernetes deployments (deprecated)
Releases
Release CI/CD examples
Release CLI tool
Release fields
Release evidence
Roll out an application incrementally
Feature flags
GitLab Pages
Tutorial: Create website from scratch
Tutorial: Build, test, and deploy your Hugo site
Create website from CI/CD template
Create website from forked sample project
Create website from project template
Create deployment for static site
Public folder
Default domain names and URLs
Custom domains
DNS records
SSL/TLS certificates
Let's Encrypt certificates
Access control
Redirects
Settings
Manage your infrastructure
Getting started
Infrastructure as Code
Terraform state
Terraform integration in merge requests
GitLab Terraform helpers
Terraform template recipes
Troubleshooting
Create Kubernetes clusters
Amazon EKS
Azure AKS
Google GKE
Civo
Connect Kubernetes clusters
Use GitOps
Tutorial: Set up Flux for GitOps
Tutorial: Deploy a Git repository using Flux
Tutorial: Deploy an OCI artifact using Flux
Migrate to Flux
Use GitLab CI/CD
Manage cluster applications
Install cert-manager
Install Ingress
Install GitLab Runner
Install Vault
Install the agent for Kubernetes
Manage the agent for Kubernetes instances
Grant users Kubernetes access
Operational container scanning
Troubleshooting
Migrate to the agent for Kubernetes
Runbooks
Monitor your application
Getting started
Tutorial: Use GitLab Observability with a Ruby on Rails application
Tutorial: Use GitLab Observability with a NodeJS application
Tutorial: Use GitLab Observability with a Django application
Tutorial: Use GitLab Observability with a Java Spring application
Tutorial: Use GitLab Observability with a .NET application
Error tracking
Integrated error tracking
Sentry error tracking
Distributed tracing
Metrics
Logs
Incident management
Alerts
Integrations
Incidents
Manage incidents
Timeline events
Linked resources
Incident management for Slack
On-call schedules
Escalation policies
Paging and notifications
Status page
Analyze GitLab usage
Value streams dashboard
Value stream analytics
AI Impact analytics
DevOps adoption by instance
DevOps adoption by group
Instance-level analytics
Usage trends
Insights
Product analytics
Instrumentation
Browser SDK
Analytics dashboards
Issue analytics
Merge request analytics
Productivity analytics
Code review analytics
Contribution analytics
Contributor analytics
Repository analytics for projects
Repository analytics for groups
CI/CD analytics
DORA metrics
Tutorial: Set up an analytics-powered project
Tutorial: Set up product analytics in a GitLab Pages website project
Experiment, beta, and GA support
Find your GitLab version
GitLab Duo
Control GitLab Duo availability
GitLab Duo experiments
GitLab Duo use cases
GitLab Duo data usage
Code Suggestions
Supported extensions and languages
Troubleshooting
Repository X-Ray
GitLab Duo Chat
Ask Duo Chat
Control Duo Chat availability
Duo Chat best practices
Duo Chat troubleshooting
GitLab Duo Workflow
Extend
Getting started
Integrations
Project integrations
Akismet
Apple App Store Connect
Arkose Protect
Asana
Atlassian Bamboo
AWS CodePipeline
Beyond Identity
Datadog
Diagrams.net
Diffblue Cover
Discord Notifications
Elasticsearch
Troubleshooting
Emails on push
External issue trackers
Bugzilla
ClickUp
Custom issue tracker
Engineering Workflow Management (EWM)
Phorge
Redmine
YouTrack
GitGuardian
GitHub
GitLab for Slack app
Troubleshooting
Gitpod
Gmail actions
Google Chat
Google Play
Harbor
irker (IRC gateway)
Jenkins
Jira
Jira issue integration
Jira issue management
Tutorial: Create Jira credentials
Troubleshooting
Jira development panel
GitLab for Jira Cloud app
Jira DVCS connector
Troubleshooting
Kroki
Mailgun
Marketplace partners
Matrix notifications
Mattermost notifications
Mattermost slash commands
Microsoft Teams notifications
MLflow
Mock CI
Pipeline status emails
Pivotal Tracker
PlantUML
Pumble
reCAPTCHA
Slack notifications (deprecated)
Slack slash commands
Snowflake
Sourcegraph
Squash TM
Telegram
Trello Power-Ups
Unify Circuit
Webex Teams
Zoekt
Webhooks
Webhook events
Rake tasks
REST API
REST API resources
.gitignore (templates)
.gitlab-ci.yml (templates)
Access requests
Agent for Kubernetes
Alert Management
Appearance (application)
Applications
Audit events
Avatar
Badges (project)
Badges (group)
Branches
Broadcast messages
Code Suggestions
Commits
Composer
Conan
Container registry
Container registry protection rules
Custom attributes
Database migrations
Debian
Debian group distributions
Debian project distributions
Dependencies
Dependency list export
Dependency Proxy
Deploy keys
Deploy tokens
Deployments
Discussions
Dockerfile (templates)
DORA4 metrics
Emoji reactions
Environments
Epics (deprecated)
Error tracking
Events
Experiments
External status checks
Feature flags
Feature flag user lists
Freeze periods
Geo nodes (deprecated)
Geo sites
GitLab Duo Chat completions
GitLab Pages
Go Proxy
Google Cloud integration
Groups
Access tokens
Activity analytics
Epic boards
Import and export
Issue boards
Iterations
Labels
Migration by direct transfer
Milestones
Protected branches
Protected environments
Relations export
Releases
Repository storage moves
Service accounts
SSH certificates
Variables
Wikis
Helm
Import
Instance-level CI/CD variables
Integrations
Invitations
Issue boards (project)
Issues
Issues (epic)
Issues statistics
Iterations (project)
Jobs
Job artifacts
Job token scopes
Keys
Labels (project)
License
Licenses (templates)
Linked epics
Links (issue)
Links (epic)
Lint .gitlab-ci.yml
Markdown
Marketplace
Maven
Member Roles
Members
Merge request approvals
Merge request context commits
Merge requests
Merge trains
Metadata
Milestones (project)
Model registry
Namespaces
Notes (comments)
Draft notes
Notification settings
npm
NuGet
Packages
Pages domains
Personal access tokens
Pipelines schedules
Pipeline trigger tokens
Pipelines
Plan limits
Product analytics
Project access tokens
Project aliases
Project import/export
Project relations export
Project remote mirrors
Project repository storage moves
Project statistics
Project templates
Project vulnerabilities
Projects
Protected branches
Project-level protected environments
Protected packages
Protected tags
PyPI
Releases
Release links
Repositories
Repository files
Repository submodules
Resource group
Resource iteration events
Resource label events
Resource milestone events
Resource state events
Resource weight events
Ruby gems
Runners
SAML
SCIM
Search
Search migrations
Secure files
Settings (application)
Sidekiq metrics
Sidekiq queues
Snippet repository storage moves
Snippets
Snippets (project)
Statistics (application)
Suggestions
System hooks
Tags
Terraform registry
To-Do lists
Topics
Service Data
Users
Variables (project)
Version
Vulnerabilities
Vulnerability export
Vulnerability Findings
Wikis (project)
Automate storage management
Deprecations and removals
OpenAPI
GraphQL API
Run GraphQL API queries and mutations
GraphQL API resources
Audit event streaming for instances
Audit event streaming for top-level groups
Create audit report (example)
Identify issue boards (example)
List branch rules for project (example)
Query users (example)
Use custom emojis (example)
Removed items
OAuth 2.0 identity provider API
Editor and IDE extensions
Visual Studio Code
JetBrains IDEs
Troubleshooting
Visual Studio
Troubleshooting
Neovim
Troubleshooting
GitLab CLI (glab)
Contribute
Contribute to GitLab
Tutorial: Make a GitLab contribution
Contribute code with the Web IDE
Configure the Gitpod development environment
Contribute code with Gitpod
Configure GDK-in-a-box
Install the GDK development environment
Contribute code with GDK
Create a merge request
Architecture
Adding a new Service Component
Development Rake tasks
Mass insert Rails models
Development processes
AI features
Duo Chat
Embeddings
Working with prompts
Glossary
Serving Models locally
Avoiding required stops
Changelog entries
ChatOps on GitLab.com
Cloud Connector
Architecture
Code review guidelines
Danger bot
Deprecation guidelines
EE features
Emails
Experiments
Implementing experiments
Testing experiments
Experiment code reviews
Experiment rollouts
Feature flags for GitLab development
Controlling feature flags
Feature flags API
FIPS compliance
Framework - DeclarativePolicy
GitLab Dedicated features
Issues workflow
Labels
Merge request concepts
Merge request diffs development guide
Working with diffs
Application and rate limit guidelines
Frontend overview
Mergeability framework
Performance guidelines
Merge request workflow
Reusing Abstractions
Ruby upgrade guidelines
Secure partner onboarding process
Testing standards and styles
Flaky tests
Frontend testing standards and style guidelines
Review apps
Smoke tests
Testing best practices
Testing levels
Testing Rails migrations
Testing Rake tasks
Testing (contract)
Writing consumer tests
Writing provider tests
Testing (end to end)
Beginner's guide to writing end-to-end tests
Best practices when writing end-to-end tests
Dynamic element validation
Flows in GitLab QA
Page objects in GitLab QA
Resource class in GitLab QA
Migrate Capybara to Chemlab
Execution context selection
End-to-end test pipelines
Running tests that require special setup
RSpec metadata for end-to-end tests
Style guide for writing end-to-end tests
Testing with feature flags
Test Infrastructure for Cloud Integrations
Troubleshooting
Translate GitLab
Externalization
Translation
Proofreading
Merging
Development style guides
Advanced search migration style guide
API style guide
Frontend style guides
Gemfile guidelines
Go standards and style guidelines
Dependency management in Go
Managing Go versions
GraphQL API style guide
Shell command guidelines
HTML style guide
JavaScript style guide
Python guidelines
RuboCop rule guidelines
Ruby style guide
SCSS style guide
Secure coding guidelines
Shell scripting standards and style guidelines
TypeScript style guide
Vue style guide
Feature development
ActivityPub
ActivityPub actors
Releases actor
Advanced search
AI
Application Settings
Approval rules
Audit events
Auto DevOps
Built-in project templates
Cells
CI/CD
Documenting keywords
Contribute to the CI/CD schema
CI/CD component development
CI/CD template development
Pipeline Wizard
New partitioned CI/CD tables
Code intelligence
Code Owners
Code Suggestions
Source Code Management
Gitaly touch points
Push Rules development guidelines
Data science
Model registry
Data Seeder
Database
Adding database indexes
Database required stops
Add a foreign key constraint to an existing column
Avoiding downtime in migrations
Batched background migrations
Batch iteration in a tree hierarchy
Case study - filtering by label
Case study - namespaces storage statistics
CI mirrored tables
ClickHouse
ClickHouse within GitLab
GitLab activity data in ClickHouse
Merge request analytics with ClickHouse
Optimizing query execution
Tiered storages in ClickHouse
Database Dictionary
Database Lab and Postgres.ai
Database load balancing
Database migration pipeline
Database review guidelines
Database check-migrations job
Delete existing migrations
Enums
Foreign keys and associations
Introducing a new database migration version
Layout and access patterns
Maintenance operations
Migrations style guide
Multiple databases
Loose Foreign Keys
Migrations for multiple databases
NOT NULL constraints
Ordering table columns
Pagination guidelines
Pagination performance guidelines
Keyset pagination
Efficient IN operator queries
Post-deployment migrations
Query comments with Marginalia
Query count limits
Query performance guidelines
Query Recorder
Single Table Inheritance
SQL guidelines
Strings and the Text data type
Swapping tables
Table partitioning
Date range
Hash
Int range
List
Troubleshooting and debugging
Understanding EXPLAIN plans
Design and UI
Development seed files
Distributed tracing
Frontend development
Accessibility
Best practices
Automated testing
Architecture
Content Editor
Customizable dashboards
Design tokens
Diagrams.net
Merge request widget extensions
Registry architecture
Source editor
Storybook
Widgets
Dark mode
Dependencies
Design patterns
Event tracking
Emojis
FAQ
Guides
Getting started
Migrating from Vuex
Onboarding course
Lesson 1
Vue 3 migration
Icons and SVG illustrations
Keyboard shortcuts
Logging
Sentry
Performance
Security
Tech Stack
Axios
GraphQL
HAML
ViewComponent
Vue
Vuex
Tooling
Troubleshooting
Type hinting
Geo
Geo framework
Geo proxying
Git LFS
Git object deduplication
Gitaly
GitLab Flavored Markdown (GLFM)
Reference processing
GitLab Shell
Features
GitLab-sshd
Processes
GraphQL
GraphQL authorization
GraphQL BatchLoader
GraphQL pagination
GraphQL Pro
GraphQL API merge request checklist
Group-level project templates
Import (Bitbucket Cloud)
Import (Bitbucket Server)
Import (GitHub)
Import (Migration by direct transfer)
Add relations to direct transfer importer
Import (Migration by file export)
Import (test project)
Identity verification
Integrations
Internal analytics
Internal event tracking
Quick start guide
Migrating to internal event tracking
Event definition guide
Metric definition guide
Local setup and debugging
Metrics
Metrics dictionary guide
Metrics instrumentation guide
Metrics lifecycle
Service Ping
Troubleshooting
Review guidelines
Internal API
Internal allowed API
Internal users
Issuable-like Rails models utilities
Issue types
Jenkins in local environments
Jira development environment
JSON guidelines
Kubernetes integration
Logging
Observability for stage groups
Dashboards
Stage group dashboard
Error budget detail
Package
Package settings
Package structure
Support new formats
Cleanup policies
Debian repository
Dependency proxy
Harbor registry
Permissions
Custom roles
Product Qualified Lead (PQL)
Pry debugging
VS Code debugging
Build and deploy real-time view components
Redis
Remote Development developer documentation
Repository storage moves
Sec section
Analyzer development guide
CycloneDX property taxonomy
Gemnasium analyzer data
Security report ingestion
Token Revocation API
Generate test vulnerabilities
Sidekiq
Compatibility across updates
Job idempotency and job deduplication
Limited capacity worker
Logging
Worker attributes
Spam protection and CAPTCHA
Model and services
REST API spam protection
GraphQL API spam protection
Web UI spam protection
Exploratory testing
Uploads
Adding new uploads
Value Stream Analytics
Verify stage
Wikis
Work items and work item types
Workhorse
Adding new features to Workhorse
Configuration
Features that rely on Workhorse
Websocket channel support
Prometheus metrics
Organization
User experience
GitLab Development Kit
GitLab project pipelines
Contribute to GitLab Runner
Review GitLab Runner
Add new Windows version support for Docker executor
Contribute to GitLab Pages
Using dnsmasq to dynamically handle GitLab Pages subdomains
Contribute to GitLab Distribution
Contribute to Omnibus GitLab
Getting started
Build locally
Build Omnibus GitLab package
Build all-in-one Docker image
Information for GitLab team members
Set up a development environment
CI variables
Change package behavior
Change YAML config options
Add deprecation messages
Add new gitlab-ctl commands
Add new services
Add new software definitions
Create patches
Add or remove configuration options
Manage PostgreSQL versions
Omnibus mirror
Version format for the packages and Docker images
Pipelines
Work with public_attributes.json
Upgrade Chef
Handle vulnerabilities
Handle broken master pipelines
Deprecate and remove support for an OS
Contribute to GitLab Helm charts
Architecture of Cloud native GitLab Helm charts
Backup and Restore
Goals
Architecture
Design Decisions
Resource Usage
Environment setup
Style guide
Versioning and release
Troubleshooting
Contribute to GitLab Operator
CI/CD configuration
Dependency on GitLab Charts
Development installation
OpenShift cluster setup
Publish to OperatorHub
Provision and deploy
RedHat certification
RedHat certification full
Versioning and releases
Test OLM
Contribute to GitLab Design System
Contribute to documentation
Style guide
Recommended word list
Product availability details
Feature flags
Experiment and beta features
Deprecations and removals
Metadata
GraphQL
REST API
Topic types
Concepts
Tasks
Reference
Troubleshooting
Top-level
Getting started
Tutorials
Glossaries
Version-specific changes
Workflow
/help
Drawer content
Testing
markdownlint
Vale
Site architecture
Global navigation
Folder structure
Deployment process
Documentation review apps
Automation
Backport documentation changes
Redirects
Solutions
Cloud
AWS Solutions
GitLab partnership qualifications from AWS
GitLab AWS integrations index
GitLab Instances on AWS
Provision GitLab on a single EC2 instance in AWS
SRE considerations for Gitaly on AWS
GitLab and AWS Integration Tutorials
Coding Languages and Frameworks
Solutions Index for Rust
Integrations
ServiceNow
About
Use of generative AI
Collapse sidebar
Help us learn about your current experience with the documentation. Take the
survey!
ON THIS PAGE
ON THIS PAGE
* Installation
* Upgrade
* Uninstall
* Windows troubleshooting
* Get runner logs
* I get a PathTooLongException during my builds on Windows
* a) Use Git with core.longpaths enabled
* b) Use NTFSSecurity tools for PowerShell
* I can’t run Windows BASH scripts; I’m getting The system cannot find the
batch label specified - buildscript
* How can I get colored output on the web terminal?
* The service did not start due to a logon failure error when starting service
* Job marked as success or failed incorrectly
* Job marked as success and terminated midway using Kubernetes executor
* Docker executor: unsupported Windows Version
* Kubernetes executor: unsupported Windows Version
* I’m using a mapped network drive and my build cannot find the correct path
* The build container is unable to connect to service containers
* The job cannot create a build directory and fails with an error
* Blank lines for Windows Subsystem for Linux (WSL) STDOUT output in job logs
INSTALL GITLAB RUNNER ON WINDOWS
Tier: Free, Premium, Ultimate
Offering: GitLab.com, Self-managed
To install and run GitLab Runner on Windows you need:
* Git, which can be installed from the official site
* A password for your user account, if you want to run it under your user
account rather than the Built-in System Account.
INSTALLATION
caution
With GitLab Runner 10, the executable was renamed to gitlab-runner.
1. Create a folder somewhere in your system, ex.: C:\GitLab-Runner.
2. Download the binary for 64-bit or 32-bit and put it into the folder you
created. The following assumes you have renamed the binary to
gitlab-runner.exe (optional). You can download a binary for every available
version as described in Bleeding Edge - download any other tagged release.
3. Make sure to restrict the Write permissions on the GitLab Runner directory
and executable. If you do not set these permissions, regular users can
replace the executable with their own and run arbitrary code with elevated
privileges.
4. Run an elevated command prompt:
5. Register a runner.
6. Install GitLab Runner as a service and start it. You can either run the
service using the Built-in System Account (recommended) or using a user
account.
Run service using Built-in System Account (under directory created in step
1. from above, ex.: C:\GitLab-Runner)
cd C:\GitLab-Runner
.\gitlab-runner.exe install
.\gitlab-runner.exe start
Run service using user account (under directory created in step 1. from
above, ex.: C:\GitLab-Runner)
You have to enter a valid password for the current user account, because
it’s required to start the service by Windows:
cd C:\GitLab-Runner
.\gitlab-runner.exe install --user ENTER-YOUR-USERNAME --password ENTER-YOUR-PASSWORD
.\gitlab-runner.exe start
See the troubleshooting section if you encounter any errors during the
GitLab Runner installation.
7. (Optional) Update the runner’s concurrent value in
C:\GitLab-Runner\config.toml to allow multiple concurrent jobs as detailed
in advanced configuration details. Additionally, you can use the advanced
configuration details to update your shell executor to use Bash or
PowerShell rather than Batch.
Voila! Runner is installed, running, and will start again after each system
reboot. Logs are stored in Windows Event Log.
UPGRADE
1. Stop the service (you need an elevated command prompt as before):
cd C:\GitLab-Runner
.\gitlab-runner.exe stop
2. Download the binary for 64-bit or 32-bit and replace runner’s executable.
You can download a binary for every available version as described in
Bleeding Edge - download any other tagged release.
3. Start the service:
.\gitlab-runner.exe start
UNINSTALL
From an elevated command prompt:
cd C:\GitLab-Runner
.\gitlab-runner.exe stop
.\gitlab-runner.exe uninstall
cd ..
rmdir /s GitLab-Runner
WINDOWS TROUBLESHOOTING
Make sure that you read the FAQ section which describes some of the most common
problems with GitLab Runner.
If you encounter an error like The account name is invalid, try:
# Add \. before the username
.\gitlab-runner.exe install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-PASSWORD"
If you encounter a The service did not start due to a logon failure error while
starting the service, please look in the FAQ to check how to resolve the
problem.
If you don’t have a Windows Password, the GitLab Runner service won’t start but
you can use the Built-in System Account.
If you have issues with the Built-in System Account, please read Configure the
Service to Start Up with the Built-in System Account on Microsoft’s support
website.
GET RUNNER LOGS
When you run .\gitlab-runner.exe install it installs gitlab-runner as a Windows
service. You can find the logs in the Event Viewer with the provider name
gitlab-runner.
If you don’t have access to the GUI, in PowerShell, you can run Get-WinEvent.
PS C:\> Get-WinEvent -ProviderName gitlab-runner
ProviderName: gitlab-runner
TimeCreated Id LevelDisplayName Message
----------- -- ---------------- -------
2/4/2021 6:20:14 AM 1 Information [session_server].listen_address not defined, session endpoints disabled builds=0...
2/4/2021 6:20:14 AM 1 Information listen_address not defined, metrics & debug endpoints disabled builds=0...
2/4/2021 6:20:14 AM 1 Information Configuration loaded builds=0...
2/4/2021 6:20:14 AM 1 Information Starting multi-runner from C:\config.toml... builds=0...
I GET A PATHTOOLONGEXCEPTION DURING MY BUILDS ON WINDOWS
This is caused by tools like npm which will sometimes generate directory
structures with paths more than 260 characters in length. There are two possible
fixes you can adopt to solve the problem.
A) USE GIT WITH CORE.LONGPATHS ENABLED
You can avoid the problem by using Git to clean your directory structure, first
run git config --system core.longpaths true from the command line and then set
your project to use git fetch from the GitLab CI project settings page.
B) USE NTFSSECURITY TOOLS FOR POWERSHELL
The NTFSSecurity PowerShell module provides a Remove-Item2 method which supports
long paths. GitLab Runner will detect it if it is available and automatically
make use of it.
I CAN’T RUN WINDOWS BASH SCRIPTS; I’M GETTING THE SYSTEM CANNOT FIND THE BATCH
LABEL SPECIFIED - BUILDSCRIPT
You need to prepend call to your Batch file line in .gitlab-ci.yml so that it
looks like call C:\path\to\test.bat. Here is a more complete example:
before_script:
- call C:\path\to\test.bat
Additional info can be found under issue #1025.
HOW CAN I GET COLORED OUTPUT ON THE WEB TERMINAL?
Short answer:
Make sure that you have the ANSI color codes in your program’s output. For the
purposes of text formatting, assume that you’re running in a UNIX ANSI terminal
emulator (because that’s what the webUI’s output is).
Long Answer:
The web interface for GitLab CI emulates a UNIX ANSI terminal (at least
partially). The gitlab-runner pipes any output from the build directly to the
web interface. That means that any ANSI color codes that are present will be
honored.
Older versions of Windows’ CMD terminal (before Win10 version 1511) do not
support ANSI color codes - they use win32 (ANSI.SYS) calls instead which are not
present in the string to be displayed. When writing cross-platform programs, a
developer will typically use ANSI color codes by default and convert them to
win32 calls when running on a Windows system (example: Colorama).
If your program is doing the above, then you need to disable that conversion for
the CI builds so that the ANSI codes remain in the string.
See GitLab CI YAML docs for an example using PowerShell and issue #332 for more
information.
THE SERVICE DID NOT START DUE TO A LOGON FAILURE ERROR WHEN STARTING SERVICE
When installing and starting the GitLab Runner service on Windows you can meet
with such error:
gitlab-runner install --password WINDOWS_MACHINE_PASSWORD
gitlab-runner start
FATA[0000] Failed to start GitLab Runner: The service did not start due to a logon failure.
This error can occur when the user used to execute the service doesn’t have the
SeServiceLogonRight permission. In this case, you need to add this permission
for the chosen user and then try to start the service again.
1. Go to Control Panel > System and Security > Administrative Tools.
2. Open the Local Security Policy tool.
3. Choose the Security Settings > Local Policies > User Rights Assignment on
the list on the left.
4. Open the Log on as a service on the list on the right.
5. Click the Add User or Group… button.
6. Add the user (“by hand” or using Advanced… button) and apply the settings.
According to Microsoft’s documentation this should work for: Windows Vista,
Windows Server 2008, Windows 7, Windows 8.1, Windows Server 2008 R2, Windows
Server 2012 R2, Windows Server 2012, and Windows 8.
The Local Security Policy tool may be not available in some Windows versions -
for example in “Home Edition” variant of each version.
After adding the SeServiceLogonRight for the user used in service configuration,
the command gitlab-runner start should finish without failures and the service
should be started properly.
JOB MARKED AS SUCCESS OR FAILED INCORRECTLY
Most Windows programs output exit code 0 for success. However, some programs
don’t return an exit code or have a different value for success. An example is
the Windows tool robocopy. The following .gitlab-ci.yml fails, even though it
should be successful, due to the exit code output by robocopy:
test:
stage: test
script:
- New-Item -type Directory -Path ./source
- New-Item -type Directory -Path ./dest
- Write-Output "Hello World!" > ./source/file.txt
- robocopy ./source ./dest
tags:
- windows
In the case above, you need to manually add an exit code check to the script:.
For example, you can create a PowerShell script:
$exitCodes = 0,1
robocopy ./source ./dest
if ( $exitCodes.Contains($LastExitCode) ) {
exit 0
} else {
exit 1
}
And change the .gitlab-ci.yml file to:
test:
stage: test
script:
- New-Item -type Directory -Path ./source
- New-Item -type Directory -Path ./dest
- Write-Output "Hello World!" > ./source/file.txt
- ./robocopyCommand.ps1
tags:
- windows
Also, be careful of the difference between return and exit when using PowerShell
functions. While exit 1 will mark a job as failed, return 1 will not.
JOB MARKED AS SUCCESS AND TERMINATED MIDWAY USING KUBERNETES EXECUTOR
Please see Job execution.
DOCKER EXECUTOR: UNSUPPORTED WINDOWS VERSION
GitLab Runner checks the version of Windows Server to verify that it’s
supported.
It does this by running docker info.
If GitLab Runner fails to start with the following error, but with no Windows
Server version specified, then the likely root cause is that the Docker version
is too old.
Preparation failed: detecting base image: unsupported Windows Version: Windows Server Datacenter
The error should contain detailed information about the Windows Server version,
which is then compared with the versions that GitLab Runner supports.
unsupported Windows Version: Windows Server Datacenter Version (OS Build 18363.720)
Docker 17.06.2 on Windows Server returns the following in the output of docker
info.
Operating System: Windows Server Datacenter
The fix in this case is to upgrade the Docker version of similar age, or later,
than the Windows Server release.
KUBERNETES EXECUTOR: UNSUPPORTED WINDOWS VERSION
Kubernetes executor on Windows might fail with the following error:
Using Kubernetes namespace: gitlab-runner
ERROR: Preparation failed: prepare helper image: detecting base image: unsupported Windows Version:
Will be retried in 3s ...
ERROR: Job failed (system failure): prepare helper image: detecting base image: unsupported Windows Version:
To fix it, add node.kubernetes.io/windows-build nodeSelector in the section
[runners.kubernetes.node_selector] of your GitLab Runner config file, For
example:
[runners.kubernetes.node_selector]
"kubernetes.io/arch" = "amd64"
"kubernetes.io/os" = "windows"
"node.kubernetes.io/windows-build" = "10.0.17763"
I’M USING A MAPPED NETWORK DRIVE AND MY BUILD CANNOT FIND THE CORRECT PATH
If GitLab Runner is not being run under an administrator account and instead is
using a standard user account, mapped network drives cannot be used and you’ll
receive an error stating The system cannot find the path specified. This is
because using a service logon session creates some limitations on accessing
resources for security. Use the UNC path of your drive instead.
THE BUILD CONTAINER IS UNABLE TO CONNECT TO SERVICE CONTAINERS
To use services with Windows containers:
* Use the networking mode that creates a network for each job.
* Ensure that the FF_NETWORK_PER_BUILD feature flag is enabled.
THE JOB CANNOT CREATE A BUILD DIRECTORY AND FAILS WITH AN ERROR
When you use the GitLab-Runner with the Docker-Windows executor, a job might
fail with an error like:
fatal: cannot chdir to c:/builds/gitlab/test: Permission denied`
When this error occurs, ensure the user the Docker engine is running as has full
permissions to C:\Program Data\Docker. The Docker engine must be able to write
to this directory for certain actions, and without the correct permissions it
will fail.
Read more about configuring Docker Engine on Windows.
BLANK LINES FOR WINDOWS SUBSYSTEM FOR LINUX (WSL) STDOUT OUTPUT IN JOB LOGS
By default the STDOUT output for the Windows Subsystem for Linux (WSL) is not
UTF8 encoded and displays as blank lines in the job logs. To display the STDOUT
output, you can force UTF8 encoding for WSL by setting the WSL_UTF8 environment
variable.
job:
variables:
WSL_UTF8: "1"
HELP & FEEDBACK
DOCS
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
PRODUCT
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Join First Look to help shape new features.
FEATURE AVAILABILITY AND PRODUCT TRIALS
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
GET HELP
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post
on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab
subscription).
Request support
Sign in to GitLab.com
* Twitter
* Facebook
* YouTube
* LinkedIn
* Docs Repo
* About GitLab
* Terms
* Privacy Statement
* Cookie Preferences
* Contact
View page source - Edit in Web IDE
* Twitter
* Facebook
* YouTube
* LinkedIn
ON THIS PAGE
ON THIS PAGE
* Installation
* Upgrade
* Uninstall
* Windows troubleshooting
* Get runner logs
* I get a PathTooLongException during my builds on Windows
* a) Use Git with core.longpaths enabled
* b) Use NTFSSecurity tools for PowerShell
* I can’t run Windows BASH scripts; I’m getting The system cannot find the
batch label specified - buildscript
* How can I get colored output on the web terminal?
* The service did not start due to a logon failure error when starting service
* Job marked as success or failed incorrectly
* Job marked as success and terminated midway using Kubernetes executor
* Docker executor: unsupported Windows Version
* Kubernetes executor: unsupported Windows Version
* I’m using a mapped network drive and my build cannot find the correct path
* The build container is unable to connect to service containers
* The job cannot create a build directory and fails with an error
* Blank lines for Windows Subsystem for Linux (WSL) STDOUT output in job logs
PRIVACY PREFERENCE CENTER
* YOUR PRIVACY
* STRICTLY NECESSARY COOKIES
* FUNCTIONALITY COOKIES
* PERFORMANCE AND ANALYTICS COOKIES
* TARGETING AND ADVERTISING COOKIES
YOUR PRIVACY
When you visit any website, it may store or retrieve information on your
browser, mostly in the form of cookies. This information might be about you,
your preferences or your device and is mostly used to make the site work as you
expect it to. The information does not usually directly identify you, but it can
give you a more personalized web experience. Because we respect your right to
privacy, you can choose not to allow some types of cookies. Click on the
different category headings to find out more and change our default settings.
However, blocking some types of cookies may impact your experience of the site
and the services we are able to offer.
Cookie Policy
User ID: 23eec010-474d-483a-af7f-494ee21cd226
This User ID will be used as a unique identifier while storing and accessing
your preferences for future.
Timestamp: --
STRICTLY NECESSARY COOKIES
Always Active
These cookies are necessary for the website to function and cannot be switched
off in our systems. They are usually only set in response to actions made by you
which amount to a request for services, such as setting your privacy
preferences, enabling you to securely log into the site, filling in forms, or
using the customer checkout. GitLab processes any personal data collected
through these cookies on the basis of our legitimate interest.
Cookies Details
FUNCTIONALITY COOKIES
Functionality Cookies
These cookies enable helpful but non-essential website functions that improve
your website experience. By recognizing you when you return to our website, they
may, for example, allow us to personalize our content for you or remember your
preferences. If you do not allow these cookies then some or all of these
services may not function properly. GitLab processes any personal data collected
through these cookies on the basis of your consent
Cookies Details
PERFORMANCE AND ANALYTICS COOKIES
Performance and Analytics Cookies
These cookies allow us and our third-party service providers to recognize and
count the number of visitors on our websites and to see how visitors move around
our websites when they are using it. This helps us improve our products and
ensures that users can easily find what they need on our websites. These cookies
usually generate aggregate statistics that are not associated with an
individual. To the extent any personal data is collected through these cookies,
GitLab processes that data on the basis of your consent.
Cookies Details
TARGETING AND ADVERTISING COOKIES
Targeting and Advertising Cookies
These cookies enable different advertising related functions. They may allow us
to record information about your visit to our websites, such as pages visited,
links followed, and videos viewed so we can make our websites and the
advertising displayed on it more relevant to your interests. They may be set
through our website by our advertising partners. They may be used by those
companies to build a profile of your interests and show you relevant
advertisements on other websites. GitLab processes any personal data collected
through these cookies on the basis of your consent.
Cookies Details
Back Button
COOKIE LIST
Filter Button
Consent Leg.Interest
checkbox label label
checkbox label label
checkbox label label
Clear
checkbox label label
Apply Cancel
Confirm My Choices
Allow All